UUENCODE(1)                POSIX Programmer's Manual               UUENCODE(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       uuencode -- encode a binary file

SSYYNNOOPPSSIISS
       uuencode [[-m]] [[_f_i_l_e]] _d_e_c_o_d_e___p_a_t_h_n_a_m_e

DDEESSCCRRIIPPTTIIOONN
       The _u_u_e_n_c_o_d_e utility shall write an encoded version of the named input
       file, or standard input if no _f_i_l_e 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 _c_h_m_o_d octal or symbolic notation) of the input file and the
       _d_e_c_o_d_e___p_a_t_h_n_a_m_e, for re-creation of the file on another system that
       conforms to this volume of POSIX.1-2008.

OOPPTTIIOONNSS
       The _u_u_e_n_c_o_d_e utility shall conform to the Base Definitions volume of
       POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following option shall be supported by the implementation:

       --mm        Encode the output using the MIME Base64 algorithm described
                 in STDOUT.  If --mm is not specified, the historical algorithm
                 described in STDOUT shall be used.

OOPPEERRAANNDDSS
       The following operands shall be supported:

       _d_e_c_o_d_e___p_a_t_h_n_a_m_e
                 The pathname of the file into which the _u_u_d_e_c_o_d_e utility
                 shall place the decoded file. Specifying a _d_e_c_o_d_e___p_a_t_h_n_a_m_e
                 operand of //ddeevv//ssttddoouutt shall indicate that _u_u_d_e_c_o_d_e is to use
                 standard output. If there are characters in _d_e_c_o_d_e___p_a_t_h_n_a_m_e
                 that are not in the portable filename character set the
                 results are unspecified.

       _f_i_l_e      A pathname of the file to be encoded.

SSTTDDIINN
       See the INPUT FILES section.

IINNPPUUTT FFIILLEESS
       Input files can be files of any type.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of
       _u_u_e_n_c_o_d_e:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
   uuuueennccooddee BBaassee6644 AAllggoorriitthhmm
       The standard output shall be a text file (encoded in the character set
       of the current locale) that begins with the line:

           ""bbeeggiinn--bbaassee6644 %%ss %%ss\\nn"",, <<_m_o_d_e>, <_d_e_c_o_d_e___p_a_t_h_n_a_m_e>

       and ends with the line:

           ""========\\nn""

       In both cases, the lines shall have no preceding or trailing <blank>
       characters.

       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
       _T_a_b_l_e _4_-_2_2_, _u_u_e_n_c_o_d_e _B_a_s_e_6_4 _V_a_l_u_e_s.

                         TTaabbllee 44--2222:: uuuueennccooddee BBaassee6644 VVaalluueess

     +------+----------++------+----------++------+----------++------+----------+
     |VVaalluuee | EEnnccooddiinngg ||VVaalluuee | EEnnccooddiinngg ||VVaalluuee | EEnnccooddiinngg ||VVaalluuee | EEnnccooddiinngg |
     +------+----------++------+----------++------+----------++------+----------+
     |  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     ||      |          |
     +------+----------++------+----------++------+----------++------+----------+
       The character referenced by the index shall be placed in the output
       string.

       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
       _u_u_d_e_c_o_d_e).

       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 ''==''.  Since
       all Base64 input is an integral number of octets, only the following
       cases can arise:

        1. 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 ''=='' padding.

        2. The final quantum of encoding input is exactly 16 bits; here, the
           final unit of encoded output shall be three characters followed by
           one ''=='' padding character.

        3. The final quantum of encoding input is exactly 8 bits; here, the
           final unit of encoded output shall be two characters followed by
           two ''=='' padding characters.

       A terminating ""========"" evaluates to nothing and denotes the end of the
       encoded data.

   uuuueennccooddee HHiissttoorriiccaall AAllggoorriitthhmm
       The standard output shall be a text file (encoded in the character set
       of the current locale) that begins with the line:

           ""bbeeggiinn %%ss %%ss\\nn"" <<_m_o_d_e>, <_d_e_c_o_d_e___p_a_t_h_n_a_m_e>

       and ends with the line:

           ""eenndd\\nn""

       In both cases, the lines shall have no preceding or trailing <blank>
       characters.

       The algorithm that shall be used for lines in between bbeeggiinn and eenndd
       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 ''AA'', would be translated to ''AA''
       in the current codeset, such as 0xc1 if it were EBCDIC.)

       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 _A, _B, _C shall be converted into the four octets:

           00xx2200 ++ (((( AA >>>> 22                    )) && 00xx33FF))
           00xx2200 ++ ((((((AA <<<< 44)) || ((((BB >>>> 44)) && 00xxFF)))) && 00xx33FF))
           00xx2200 ++ ((((((BB <<<< 22)) || ((((CC >>>> 66)) && 00xx33)))) && 00xx33FF))
           00xx2200 ++ (((( CC                         )) && 00xx33FF))

       These octets then shall be translated into the local character set.

       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.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The file is expanded by 35 percent (each three octets become four, plus
       control information) causing it to take longer to transmit.

       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 _u_u_e_n_c_o_d_e 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> characters 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 _u_u_d_e_c_o_d_e.  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 _u_u_e_n_c_o_d_e can be placed in _p_a_x archives, intermixed with
       other text files in the same codeset.

EEXXAAMMPPLLEESS
       None.

RRAATTIIOONNAALLEE
       A new algorithm was added at the request of the international community
       to parallel work in RFC 2045 (MIME). As with the historical _u_u_e_n_c_o_d_e
       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, ''=='', is used to signify a special processing function.)

       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 _u_u_e_n_c_o_d_e
       algorithm does not share this property, which is the reason that a
       second algorithm was added to the ISO POSIX-2 standard.

       The string ""========"" 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.

       In an early draft, the --mm option was named --bb (for Base64), but it was
       renamed to reflect its relationship to the RFC 2045. A --uu was also
       present to invoke the default algorithm, but since this was not
       historical practice, it was omitted as being unnecessary.

       See the RATIONALE section in _u_u_d_e_c_o_d_e for the derivation of the
       //ddeevv//ssttddoouutt symbol.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_h_m_o_d, _m_a_i_l_x, _u_u_d_e_c_o_d_e

       The Base Definitions volume of POSIX.1-2008, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                          UUENCODE(1)
