'\" te
.\"  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
.\" 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
.\" http://www.opengroup.org/bookstore/.
.\" 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.
.\"  This notice shall appear on any product containing this material.
.TH UUENCODE 1C "Aug 6, 2003"
.SH NAME
uuencode, uudecode \- encode a binary file, or decode its encoded
representation
.SH SYNOPSIS
.LP
.nf
\fBuuencode\fR [\fIsource-file\fR] \fIdecode_pathname\fR
.fi

.LP
.nf
\fBuuencode\fR [\fB-m\fR] [\fIsource-file\fR] \fIdecode_pathname\fR
.fi

.LP
.nf
\fBuudecode\fR [\fB-p\fR] [\fIencoded-file\fR]
.fi

.LP
.nf
\fBuudecode\fR [\fB-o\fR \fIoutfile\fR] [\fIencoded-file\fR]
.fi

.SH DESCRIPTION
.sp
.LP
These commands encode and decode files as follows:
.SS "uuencode"
.sp
.LP
The \fBuuencode\fR utility converts a binary file into an encoded
representation that can be sent using \fBmail\fR(1). It encodes the contents of
\fIsource-file\fR, or the standard input if no \fIsource-file\fR argument is
given. The \fIdecode_pathname\fR argument is required. The
\fIdecode_pathname\fR is included in the encoded file's header as the name of
the file into which \fBuudecode\fR is to place the binary (decoded) data.
\fBuuencode\fR also includes the permission modes of \fIsource-file\fR (except
\fBsetuid\fR, \fBsetgid\fR, and sticky-bits), so that \fIdecode_pathname\fR is
recreated with those same permission modes.
.SS "uudecode"
.sp
.LP
The \fBuudecode\fR utility reads an \fIencoded-file\fR, strips off any leading
and trailing lines added by mailer programs, and recreates the original binary
data with the filename and the mode specified in the header.
.sp
.LP
The encoded file is an ordinary portable character set text file; it can be
edited by any text editor. It is best only to change the mode or
\fIdecode_pathname\fR in the header to avoid corrupting the decoded binary.
.SH OPTIONS
.sp
.LP
The following options are supported:
.SS "uuencode"
.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.RS 6n
Encodes \fIsource-file\fR using Base64 encoding and sends it to standard
output.
.RE

.SS "uudecode"
.sp
.ne 2
.na
\fB\fB-o\fR \fIoutfile\fR\fR
.ad
.RS 14n
Specifies a file pathname that should be used instead of any pathname contained
in the input data. Specifying an \fIoutfile\fR option-argument of
\fB/dev/stdout\fR indicates standard output.This allows \fBuudecode\fR to be
used in a pipeline.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 14n
Decodes \fIencoded-file\fR and sends it to standard output. This allows
\fBuudecode\fR to be used in a pipeline.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported by \fBuuencode\fR and \fBuudecode\fR:
.SS "uuencode"
.sp
.ne 2
.na
\fB\fIdecode_pathname\fR\fR
.ad
.RS 19n
The pathname of the file into which the \fBuudecode\fR utility will place the
decoded file. If there are characters in \fIdecode_pathname\fR that are not in
the portable filename character set, the results are unspecified.
.RE

.sp
.ne 2
.na
\fB\fIsource-file\fR\fR
.ad
.RS 19n
A pathname of the file to be encoded.
.RE

.SS "uudecode"
.sp
.ne 2
.na
\fB\fIencoded-file\fR\fR
.ad
.RS 16n
The pathname of a file containing the output of \fBuuencode\fR.
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBuuencode\fR
and \fBuudecode\fR when encountering files greater than or equal to 2 Gbyte (
2^31 bytes).
.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBuuencode\fR and \fBuudecode\fR: \fBLANG\fR,
\fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH OUTPUT
.sp
.LP
stdout
.SS "uuencode Base64 Algorithm"
.sp
.LP
The standard output is a text file, encoded in the character set of the current
locale, that begins with the line:
.sp
.in +2
.nf
begin-base64 %s %s\n, \fImode\fR, \fIdecode_pathname\fR
.fi
.in -2
.sp

.sp
.LP
and ends with the line:
.sp
.in +2
.nf
====
.fi
.in -2
.sp

.sp
.LP
In both cases, the lines have no preceding or trailing blank characters.
.sp
.LP
The encoding process represents 24-bit groups of input bits as output strings
of  four encoded characters. Proceeding from left to right, a 24-bit input
group is formed by concatenating three 8-bit input groups. Each 24-bit input
group  is then treated as four concatenated 6-bit groups, each of which is
translated into a single digit in the Base64 alphabet. When encoding a bit
stream by means of the Base64 encoding, the bit stream is presumed to be
ordered with the most-significant bit first. That is, the first bit in the
stream is the high-order bit in the first byte, and the eighth bit is the
low-order bit in the first byte, and so on. Each 6-bit group is used as an
index into an array of 64 printable characters, as shown in the following
table.
.sp
.in +2
.nf
Value Encoding   Value Encoding   Value Encoding   Value Encoding
  0      A         17     R         34     i         51     z
  1      B         18     S         35     j         52     0
  2      C         19     T         36     k         53     1
  3      D         20     U         37     l         54     2
  4      E         21     V         38     m         55     3
  5      F         22     W         39     n         56     4
  6      G         23     X         40     o         57     5
  7      H         24     Y         41     p         58     6
  8      I         25     Z         42     q         59     7
  9      J         26     a         43     r         60     8
 10      K         27     b         44     s         61     9
 11      L         28     c         45     t         62     +
 12      M         29     d         46     u         63     /
 13      N         30     e         47     v
 14      O         31     f         48     w        (pad)   =
 15      P         32     g         49     x
 16      Q         33     h         50     y
.fi
.in -2
.sp

.sp
.LP
The character referenced by the index is placed in the output string.
.sp
.LP
The output stream (encoded bytes) is represented in lines of no more than 76
characters each. All line breaks or other characters not found in the table are
ignored by decoding software (see \fBuudecode\fR).
.sp
.LP
Special processing is performed if fewer than 24 bits are available at the end
of a message or encapsulated part of a message. A full encoding quantum is
always completed at the end of a message. When fewer than 24 input bits are
available in an input group, zero bits are added on the right to form an
integral number of 6-bit groups. Output character positions that are not
required to represent actual input data are set to the equals (\fB=\fR)
character. Since all Base64 input is an integral number of octets, only the
following cases can arise:
.RS +4
.TP
1.
The final quantum of encoding input is an integral multiple of 24 bits.
Here, the final unit of encoded output is an integral multiple of four
characters with no '\fB=\fR ' padding.
.RE
.RS +4
.TP
2.
The final quantum of encoding input is exactly 16 bits. Here, the final unit
of encoded output is three characters followed by one '\fB=\fR' padding
character.
.RE
.RS +4
.TP
3.
The final quantum of encoding input is exactly 8 bits. Here, the final unit
of encoded output is two characters followed by two '\fB=\fR' padding
characters.
.RE
.sp
.LP
A terminating "\fB====\fR" evaluates to nothing and denotes the end of the
encoded data.
.SS "uuencode Historical Algorithm"
.sp
.LP
The standard output is a text file (encoded in the character set of the current
locale) that begins with the line:
.sp
.in +2
.nf
begin %s %s\en, \fImode\fR, \fIdecode_pathname\fR
.fi
.in -2
.sp

.sp
.LP
and ends with the line:
.sp
.in +2
.nf
end\en
.fi
.in -2
.sp

.sp
.LP
In both cases, the lines have no preceding or trailing blank characters.
.sp
.LP
The algorithm that is used for lines between \fBbegin\fR and \fBend\fR takes
three octets as input and writes four characters of output by splitting the
input at six-bit intervals into four octets, containing data in the lower six
bits only. These octets are converted to characters by adding a value of
\fB0x20\fR to each octet, so that each octet is in the range
\fB0x20\(mi0x5f\fR, and each octet is assumed to represent a printable
character. Each octect is then translated into the corresponding character
codes for the codeset in use in the current locale. For example, the octet
\fB0x41\fR, representing '\fBA\fR', would be translated to '\fBA\fR' in the
current codeset, such as \fB0xc1\fR if the codeset were \fBEBCDIC\fR.
.sp
.LP
Where the bits of two octets are combined, the least significant bits of the
first octet are shifted left and combined with the most significant bits of the
second octet shifted right. Thus, the three octets \fBA\fR, \fBB\fR, \fBC\fR
are converted into the four octets:
.sp
.in +2
.nf
0x20 + (( A >> 2                          ) & 0x3F)
0x20 + (((A << 4)  ((B >> 4) & 0xF)) & 0x3F)
0x20 + (((B << 2)  ((C >> 6) & 0x3)) & 0x3F)
0x20 + (( C                                 ) & 0x3F)
.fi
.in -2
.sp

.sp
.LP
These octets are then translated into the local character set.
.sp
.LP
Each encoded line contains a length character, equal to the number of
characters to be decoded plus \fB0x20\fR translated to the local character set
as described above, followed by the encoded characters. The maximum number of
octets to be encoded on each line is 45.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE 	ATTRIBUTE VALUE
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.sp
.LP
\fBmail\fR(1), \fBmailx\fR(1), \fBuucp\fR(1C), \fBuux\fR(1C),
\fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
The size of the encoded file is expanded by 35% (3 bytes become 4, plus control
information), causing it to take longer to transmit than the equivalent binary.
.sp
.LP
The user on the remote system who is invoking \fBuudecode\fR (typically
\fBuucp\fR) must have write permission on the file specified in the
\fIdecode_pathname\fR.
.sp
.LP
If you invoke \fBuuencode\fR and then execute \fBuudecode\fR on a file in the
same directory, you will overwrite the original file.