mirror of https://github.com/mkerrisk/man-pages
358 lines
12 KiB
Groff
358 lines
12 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "UUENCODE" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" uuencode
|
|
.SH PROLOG
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
The Linux implementation of this interface may differ (consult
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
or the interface may not be implemented on Linux.
|
|
.SH NAME
|
|
uuencode \- encode a binary file
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBuuencode\fP \fB[\fP\fB-m\fP\fB][\fP\fIfile\fP\fB]\fP \fIdecode_pathname\fP\fB\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIuuencode\fP utility shall write an encoded version of the named
|
|
input file, or standard input if no \fIfile\fP is
|
|
specified, to standard output. The output shall be encoded using one
|
|
of the algorithms described in the STDOUT section and shall
|
|
include the file access permission bits (in \fIchmod\fP octal or symbolic
|
|
notation) of the
|
|
input file and the \fIdecode_pathname\fP, for re-creation of the file
|
|
on another system that conforms to this volume of
|
|
IEEE\ Std\ 1003.1-2001.
|
|
.SH OPTIONS
|
|
.LP
|
|
The \fIuuencode\fP utility shall conform to the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
.LP
|
|
The following option shall be supported by the implementation:
|
|
.TP 7
|
|
\fB-m\fP
|
|
Encode the output using the MIME Base64 algorithm described in STDOUT.
|
|
If \fB-m\fP is not specified, the historical algorithm
|
|
described in STDOUT shall be used.
|
|
.sp
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operands shall be supported:
|
|
.TP 7
|
|
\fIdecode_pathname\fP
|
|
.sp
|
|
The pathname of the file into which the \fIuudecode\fP utility shall
|
|
place the decoded
|
|
file. Specifying a \fIdecode_pathname\fP operand of \fB/dev/stdout\fP
|
|
shall indicate that \fIuudecode\fP is to use standard output. If there
|
|
are characters in \fIdecode_pathname\fP that
|
|
are not in the portable filename character set the results are unspecified.
|
|
.TP 7
|
|
\fIfile\fP
|
|
A pathname of the file to be encoded.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
See the INPUT FILES section.
|
|
.SH INPUT FILES
|
|
.LP
|
|
Input files can be files of any type.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fIuuencode\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
Provide a default value for the internationalization variables that
|
|
are unset or null. (See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
for
|
|
the precedence of internationalization variables used to determine
|
|
the values of locale categories.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments and input files).
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic messages written to standard
|
|
error.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.SS uuencode Base64 Algorithm
|
|
.LP
|
|
The standard output shall be a text file (encoded in the character
|
|
set of the current locale) that begins with the line:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"begin-base64 %s %s\\n", <\fP\fImode\fP\fB>, <\fP\fIdecode_pathname\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
and ends with the line:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"====\\n"
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
In both cases, the lines shall have no preceding or trailing <blank>s.
|
|
.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 shall be formed by concatenating three
|
|
8-bit input groups. Each 24-bit input group then shall be
|
|
treated as four concatenated 6-bit groups, each of which shall be
|
|
translated into a single digit in the Base64 alphabet. When
|
|
encoding a bit stream via the Base64 encoding, the bit stream shall
|
|
be presumed to be ordered with the most-significant bit first.
|
|
That is, the first bit in the stream shall be the high-order bit in
|
|
the first byte, and the eighth bit shall be 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 uuencode Base64
|
|
Values .
|
|
.sp
|
|
.ce 1
|
|
\fBTable: uuencode Base64 Values\fP
|
|
.TS C
|
|
center; l1 l1 l1 l1 l1 l1 l1 l1 l1 l1 l.
|
|
\fBValue\fP \fBEncoding\fP Value \fBEncoding\fP \fBValue\fP Encoding \fBValue\fP \fBEncoding\fP \ \fB\ \fP \fB\ \fP
|
|
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 \ \ \ \ \
|
|
.TE
|
|
.LP
|
|
The character referenced by the index shall be placed in the output
|
|
string.
|
|
.LP
|
|
The output stream (encoded bytes) shall be represented in lines of
|
|
no more than 76 characters each. All line breaks or other
|
|
characters not found in the table shall be ignored by decoding software
|
|
(see \fIuudecode\fP ).
|
|
.LP
|
|
Special processing shall be performed if fewer than 24 bits are available
|
|
at the end of a message or encapsulated part of a
|
|
message. A full encoding quantum shall always be completed at the
|
|
end of a message. When fewer than 24 input bits are available in
|
|
an input group, zero bits shall be 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 shall be set to the
|
|
character \fB'='\fP . Since all Base64 input is an integral
|
|
number of octets, only the following cases can arise:
|
|
.IP " 1." 4
|
|
The final quantum of encoding input is an integral multiple of 24
|
|
bits; here, the final unit of encoded output shall be an
|
|
integral multiple of 4 characters with no \fB'='\fP padding.
|
|
.LP
|
|
.IP " 2." 4
|
|
The final quantum of encoding input is exactly 16 bits; here, the
|
|
final unit of encoded output shall be three characters
|
|
followed by one \fB'='\fP padding character.
|
|
.LP
|
|
.IP " 3." 4
|
|
The final quantum of encoding input is exactly 8 bits; here, the final
|
|
unit of encoded output shall be two characters followed
|
|
by two \fB'='\fP padding characters.
|
|
.LP
|
|
.LP
|
|
A terminating \fB"===="\fP evaluates to nothing and denotes the end
|
|
of the encoded data.
|
|
.SS uuencode Historical Algorithm
|
|
.LP
|
|
The standard output shall be a text file (encoded in the character
|
|
set of the current locale) that begins with the line:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"begin %s %s\\n" <\fP\fImode\fP\fB>, <\fP\fIdecode_pathname\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
and ends with the line:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"end\\n"
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
In both cases, the lines shall have no preceding or trailing <blank>s.
|
|
.LP
|
|
The algorithm that shall be used for lines in between \fBbegin\fP
|
|
and \fBend\fP 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 shall be converted to characters by adding a value of
|
|
0x20 to each octet, so that each octet is in the range
|
|
[0x20,0x5f], and then it shall be assumed to represent a printable
|
|
character in the ISO/IEC\ 646:1991 standard encoded
|
|
character set. It then shall be translated into the corresponding
|
|
character codes for the codeset in use in the current locale.
|
|
(For example, the octet 0x41, representing \fB'A'\fP , would be translated
|
|
to \fB'A'\fP in the current codeset, such as 0xc1
|
|
if it were EBCDIC.)
|
|
.LP
|
|
Where the bits of two octets are combined, the least significant bits
|
|
of the first octet shall be shifted left and combined with
|
|
the most significant bits of the second octet shifted right. Thus
|
|
the three octets \fIA\fP, \fIB\fP, \fIC\fP shall be converted
|
|
into the four octets:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB0x20 + (( A >> 2 ) & 0x3F)
|
|
0x20 + (((A << 4) | ((B >> 4) & 0xF)) & 0x3F)
|
|
0x20 + (((B << 2) | ((C >> 6) & 0x3)) & 0x3F)
|
|
0x20 + (( C ) & 0x3F)
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
These octets then shall be translated into the local character set.
|
|
.LP
|
|
Each encoded line contains a length character, equal to the number
|
|
of characters to be decoded plus 0x20 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 shall
|
|
be 45.
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used only for diagnostic messages.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
None.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
Successful completion.
|
|
.TP 7
|
|
>0
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
Default.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The file is expanded by 35 percent (each three octets become four,
|
|
plus control information) causing it to take longer to
|
|
transmit.
|
|
.LP
|
|
Since this utility is intended to create files to be used for data
|
|
interchange between systems with possibly different codesets,
|
|
and to represent binary data as a text file, the ISO/IEC\ 646:1991
|
|
standard was chosen for a midpoint in the algorithm as a
|
|
known reference point. The output from \fIuuencode\fP is a text file
|
|
on the local system. If the output were in the
|
|
ISO/IEC\ 646:1991 standard codeset, it might not be a text file (at
|
|
least because the <newline>s might not match), and
|
|
the goal of creating a text file would be defeated. If this text file
|
|
was then carried to another machine with the same codeset, it
|
|
would be perfectly compatible with that system's \fIuudecode\fP. If
|
|
it was transmitted
|
|
over a mail system or sent to a machine with a different codeset,
|
|
it is assumed that, as for every other text file, some
|
|
translation mechanism would convert it (by the time it reached a user
|
|
on the other system) into an appropriate codeset. This
|
|
translation only makes sense from the local codeset, not if the file
|
|
has been put into a ISO/IEC\ 646:1991 standard
|
|
representation first. Similarly, files processed by \fIuuencode\fP
|
|
can be placed in \fIpax\fP
|
|
archives, intermixed with other text files in the same codeset.
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
A new algorithm was added at the request of the international community
|
|
to parallel work in RFC\ 2045 (MIME). As with the
|
|
historical \fIuuencode\fP format, the Base64 Content-Transfer-Encoding
|
|
is designed to represent arbitrary sequences of octets in a
|
|
form that is not humanly readable. A 65-character subset of the ISO/IEC\ 646:1991
|
|
standard is used, enabling 6 bits to be
|
|
represented per printable character. (The extra 65th character, \fB'='\fP
|
|
, is used to signify a special processing
|
|
function.)
|
|
.LP
|
|
This subset has the important property that it is represented identically
|
|
in all versions of the ISO/IEC\ 646:1991 standard,
|
|
including US ASCII, and all characters in the subset are also represented
|
|
identically in all versions of EBCDIC. The historical
|
|
\fIuuencode\fP algorithm does not share this property, which is the
|
|
reason that a second algorithm was added to the
|
|
ISO\ POSIX-2 standard.
|
|
.LP
|
|
The string \fB"===="\fP was used for the termination instead of the
|
|
end used in the original format because the latter is a
|
|
string that could be valid encoded input.
|
|
.LP
|
|
In an early draft, the \fB-m\fP option was named \fB-b\fP (for Base64),
|
|
but it was renamed to reflect its relationship to the
|
|
RFC\ 2045. A \fB-u\fP was also present to invoke the default algorithm,
|
|
but since this was not historical practice, it was
|
|
omitted as being unnecessary.
|
|
.LP
|
|
See the RATIONALE section in \fIuudecode\fP for the derivation of
|
|
the \fB/dev/stdout\fP
|
|
symbol.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIchmod\fP() , \fImailx\fP , \fIuudecode\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version 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 .
|