1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved  Portions Copyright (c) 2002, X/Open Company Limited  All Rights Reserved
   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4 .\" http://www.opengroup.org/bookstore/.
   5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   6 .\"  This notice shall appear on any product containing this material.
   7 .TH UUENCODE 1C "Aug 6, 2003"
   8 .SH NAME
   9 uuencode, uudecode \- encode a binary file, or decode its encoded
  10 representation
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBuuencode\fR [\fIsource-file\fR] \fIdecode_pathname\fR
  15 .fi
  16 
  17 .LP
  18 .nf
  19 \fBuuencode\fR [\fB-m\fR] [\fIsource-file\fR] \fIdecode_pathname\fR
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fBuudecode\fR [\fB-p\fR] [\fIencoded-file\fR]
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fBuudecode\fR [\fB-o\fR \fIoutfile\fR] [\fIencoded-file\fR]
  30 .fi
  31 
  32 .SH DESCRIPTION
  33 .sp
  34 .LP
  35 These commands encode and decode files as follows:
  36 .SS "uuencode"
  37 .sp
  38 .LP
  39 The \fBuuencode\fR utility converts a binary file into an encoded
  40 representation that can be sent using \fBmail\fR(1). It encodes the contents of
  41 \fIsource-file\fR, or the standard input if no \fIsource-file\fR argument is
  42 given. The \fIdecode_pathname\fR argument is required. The
  43 \fIdecode_pathname\fR is included in the encoded file's header as the name of
  44 the file into which \fBuudecode\fR is to place the binary (decoded) data.
  45 \fBuuencode\fR also includes the permission modes of \fIsource-file\fR (except
  46 \fBsetuid\fR, \fBsetgid\fR, and sticky-bits), so that \fIdecode_pathname\fR is
  47 recreated with those same permission modes.
  48 .SS "uudecode"
  49 .sp
  50 .LP
  51 The \fBuudecode\fR utility reads an \fIencoded-file\fR, strips off any leading
  52 and trailing lines added by mailer programs, and recreates the original binary
  53 data with the filename and the mode specified in the header.
  54 .sp
  55 .LP
  56 The encoded file is an ordinary portable character set text file; it can be
  57 edited by any text editor. It is best only to change the mode or
  58 \fIdecode_pathname\fR in the header to avoid corrupting the decoded binary.
  59 .SH OPTIONS
  60 .sp
  61 .LP
  62 The following options are supported:
  63 .SS "uuencode"
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fB-m\fR\fR
  68 .ad
  69 .RS 6n
  70 Encodes \fIsource-file\fR using Base64 encoding and sends it to standard
  71 output.
  72 .RE
  73 
  74 .SS "uudecode"
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fB-o\fR \fIoutfile\fR\fR
  79 .ad
  80 .RS 14n
  81 Specifies a file pathname that should be used instead of any pathname contained
  82 in the input data. Specifying an \fIoutfile\fR option-argument of
  83 \fB/dev/stdout\fR indicates standard output.This allows \fBuudecode\fR to be
  84 used in a pipeline.
  85 .RE
  86 
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fB-p\fR\fR
  91 .ad
  92 .RS 14n
  93 Decodes \fIencoded-file\fR and sends it to standard output. This allows
  94 \fBuudecode\fR to be used in a pipeline.
  95 .RE
  96 
  97 .SH OPERANDS
  98 .sp
  99 .LP
 100 The following operands are supported by \fBuuencode\fR and \fBuudecode\fR:
 101 .SS "uuencode"
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fIdecode_pathname\fR\fR
 106 .ad
 107 .RS 19n
 108 The pathname of the file into which the \fBuudecode\fR utility will place the
 109 decoded file. If there are characters in \fIdecode_pathname\fR that are not in
 110 the portable filename character set, the results are unspecified.
 111 .RE
 112 
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fIsource-file\fR\fR
 117 .ad
 118 .RS 19n
 119 A pathname of the file to be encoded.
 120 .RE
 121 
 122 .SS "uudecode"
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fIencoded-file\fR\fR
 127 .ad
 128 .RS 16n
 129 The pathname of a file containing the output of \fBuuencode\fR.
 130 .RE
 131 
 132 .SH USAGE
 133 .sp
 134 .LP
 135 See \fBlargefile\fR(5) for the description of the behavior of \fBuuencode\fR
 136 and \fBuudecode\fR when encountering files greater than or equal to 2 Gbyte (
 137 2^31 bytes).
 138 .SH ENVIRONMENT VARIABLES
 139 .sp
 140 .LP
 141 See \fBenviron\fR(5) for descriptions of the following environment variables
 142 that affect the execution of \fBuuencode\fR and \fBuudecode\fR: \fBLANG\fR,
 143 \fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 144 .SH OUTPUT
 145 .sp
 146 .LP
 147 stdout
 148 .SS "uuencode Base64 Algorithm"
 149 .sp
 150 .LP
 151 The standard output is a text file, encoded in the character set of the current
 152 locale, that begins with the line:
 153 .sp
 154 .in +2
 155 .nf
 156 begin-base64 %s %s\n, \fImode\fR, \fIdecode_pathname\fR
 157 .fi
 158 .in -2
 159 .sp
 160 
 161 .sp
 162 .LP
 163 and ends with the line:
 164 .sp
 165 .in +2
 166 .nf
 167 ====
 168 .fi
 169 .in -2
 170 .sp
 171 
 172 .sp
 173 .LP
 174 In both cases, the lines have no preceding or trailing blank characters.
 175 .sp
 176 .LP
 177 The encoding process represents 24-bit groups of input bits as output strings
 178 of  four encoded characters. Proceeding from left to right, a 24-bit input
 179 group is formed by concatenating three 8-bit input groups. Each 24-bit input
 180 group  is then treated as four concatenated 6-bit groups, each of which is
 181 translated into a single digit in the Base64 alphabet. When encoding a bit
 182 stream by means of the Base64 encoding, the bit stream is presumed to be
 183 ordered with the most-significant bit first. That is, the first bit in the
 184 stream is the high-order bit in the first byte, and the eighth bit is the
 185 low-order bit in the first byte, and so on. Each 6-bit group is used as an
 186 index into an array of 64 printable characters, as shown in the following
 187 table.
 188 .sp
 189 .in +2
 190 .nf
 191 Value Encoding   Value Encoding   Value Encoding   Value Encoding
 192   0      A         17     R         34     i         51     z
 193   1      B         18     S         35     j         52     0
 194   2      C         19     T         36     k         53     1
 195   3      D         20     U         37     l         54     2
 196   4      E         21     V         38     m         55     3
 197   5      F         22     W         39     n         56     4
 198   6      G         23     X         40     o         57     5
 199   7      H         24     Y         41     p         58     6
 200   8      I         25     Z         42     q         59     7
 201   9      J         26     a         43     r         60     8
 202  10      K         27     b         44     s         61     9
 203  11      L         28     c         45     t         62     +
 204  12      M         29     d         46     u         63     /
 205  13      N         30     e         47     v
 206  14      O         31     f         48     w        (pad)   =
 207  15      P         32     g         49     x
 208  16      Q         33     h         50     y
 209 .fi
 210 .in -2
 211 .sp
 212 
 213 .sp
 214 .LP
 215 The character referenced by the index is placed in the output string.
 216 .sp
 217 .LP
 218 The output stream (encoded bytes) is represented in lines of no more than 76
 219 characters each. All line breaks or other characters not found in the table are
 220 ignored by decoding software (see \fBuudecode\fR).
 221 .sp
 222 .LP
 223 Special processing is performed if fewer than 24 bits are available at the end
 224 of a message or encapsulated part of a message. A full encoding quantum is
 225 always completed at the end of a message. When fewer than 24 input bits are
 226 available in an input group, zero bits are added on the right to form an
 227 integral number of 6-bit groups. Output character positions that are not
 228 required to represent actual input data are set to the equals (\fB=\fR)
 229 character. Since all Base64 input is an integral number of octets, only the
 230 following cases can arise:
 231 .RS +4
 232 .TP
 233 1.
 234 The final quantum of encoding input is an integral multiple of 24 bits.
 235 Here, the final unit of encoded output is an integral multiple of four
 236 characters with no '\fB=\fR ' padding.
 237 .RE
 238 .RS +4
 239 .TP
 240 2.
 241 The final quantum of encoding input is exactly 16 bits. Here, the final unit
 242 of encoded output is three characters followed by one '\fB=\fR' padding
 243 character.
 244 .RE
 245 .RS +4
 246 .TP
 247 3.
 248 The final quantum of encoding input is exactly 8 bits. Here, the final unit
 249 of encoded output is two characters followed by two '\fB=\fR' padding
 250 characters.
 251 .RE
 252 .sp
 253 .LP
 254 A terminating "\fB====\fR" evaluates to nothing and denotes the end of the
 255 encoded data.
 256 .SS "uuencode Historical Algorithm"
 257 .sp
 258 .LP
 259 The standard output is a text file (encoded in the character set of the current
 260 locale) that begins with the line:
 261 .sp
 262 .in +2
 263 .nf
 264 begin %s %s\en, \fImode\fR, \fIdecode_pathname\fR
 265 .fi
 266 .in -2
 267 .sp
 268 
 269 .sp
 270 .LP
 271 and ends with the line:
 272 .sp
 273 .in +2
 274 .nf
 275 end\en
 276 .fi
 277 .in -2
 278 .sp
 279 
 280 .sp
 281 .LP
 282 In both cases, the lines have no preceding or trailing blank characters.
 283 .sp
 284 .LP
 285 The algorithm that is used for lines between \fBbegin\fR and \fBend\fR takes
 286 three octets as input and writes four characters of output by splitting the
 287 input at six-bit intervals into four octets, containing data in the lower six
 288 bits only. These octets are converted to characters by adding a value of
 289 \fB0x20\fR to each octet, so that each octet is in the range
 290 \fB0x20\(mi0x5f\fR, and each octet is assumed to represent a printable
 291 character. Each octect is then translated into the corresponding character
 292 codes for the codeset in use in the current locale. For example, the octet
 293 \fB0x41\fR, representing '\fBA\fR', would be translated to '\fBA\fR' in the
 294 current codeset, such as \fB0xc1\fR if the codeset were \fBEBCDIC\fR.
 295 .sp
 296 .LP
 297 Where the bits of two octets are combined, the least significant bits of the
 298 first octet are shifted left and combined with the most significant bits of the
 299 second octet shifted right. Thus, the three octets \fBA\fR, \fBB\fR, \fBC\fR
 300 are converted into the four octets:
 301 .sp
 302 .in +2
 303 .nf
 304 0x20 + (( A >> 2                          ) & 0x3F)
 305 0x20 + (((A << 4)  ((B >> 4) & 0xF)) & 0x3F)
 306 0x20 + (((B << 2)  ((C >> 6) & 0x3)) & 0x3F)
 307 0x20 + (( C                                 ) & 0x3F)
 308 .fi
 309 .in -2
 310 .sp
 311 
 312 .sp
 313 .LP
 314 These octets are then translated into the local character set.
 315 .sp
 316 .LP
 317 Each encoded line contains a length character, equal to the number of
 318 characters to be decoded plus \fB0x20\fR translated to the local character set
 319 as described above, followed by the encoded characters. The maximum number of
 320 octets to be encoded on each line is 45.
 321 .SH EXIT STATUS
 322 .sp
 323 .LP
 324 The following exit values are returned:
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fB0\fR\fR
 329 .ad
 330 .RS 6n
 331 Successful completion.
 332 .RE
 333 
 334 .sp
 335 .ne 2
 336 .na
 337 \fB\fB>0\fR\fR
 338 .ad
 339 .RS 6n
 340 An error occurred.
 341 .RE
 342 
 343 .SH ATTRIBUTES
 344 .sp
 345 .LP
 346 See \fBattributes\fR(5) for descriptions of the following attributes:
 347 .sp
 348 
 349 .sp
 350 .TS
 351 box;
 352 c | c
 353 l | l .
 354 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 355 _
 356 Interface Stability     Standard
 357 .TE
 358 
 359 .SH SEE ALSO
 360 .sp
 361 .LP
 362 \fBmail\fR(1), \fBmailx\fR(1), \fBuucp\fR(1C), \fBuux\fR(1C),
 363 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
 364 .SH NOTES
 365 .sp
 366 .LP
 367 The size of the encoded file is expanded by 35% (3 bytes become 4, plus control
 368 information), causing it to take longer to transmit than the equivalent binary.
 369 .sp
 370 .LP
 371 The user on the remote system who is invoking \fBuudecode\fR (typically
 372 \fBuucp\fR) must have write permission on the file specified in the
 373 \fIdecode_pathname\fR.
 374 .sp
 375 .LP
 376 If you invoke \fBuuencode\fR and then execute \fBuudecode\fR on a file in the
 377 same directory, you will overwrite the original file.