diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/uuencode.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/uuencode.1p | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/uuencode.1p b/man-pages-posix-2003/man1p/uuencode.1p new file mode 100644 index 0000000..4cb4c8b --- /dev/null +++ b/man-pages-posix-2003/man1p/uuencode.1p @@ -0,0 +1,357 @@ +.\" 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 . |