UUENCODE(1POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 UUENCODE(1POSIX) 💖

okay bestie, we're doing the POSIX Programmer's Manual version of uuencode — that's the manual name right there in the title, so now you know. Let's get into it 🫶

✨ PROLOG ✨

So like, heads up: 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 at all. ngl that's just how it is. 💀

🌸 NAME 🌸

uuencode — encode a binary file

🎀 SYNOPSIS 🎀

uuencode [-m] [file] decode_pathname

💅 DESCRIPTION 💅

okay so the uuencode utility shall write an encoded version of the named input file, or standard input if no file is specified, to standard output. like, it takes your file and makes it into text, iconic behavior honestly.

The output shall be encoded using one of the algorithms described in the STDOUT section (they're down there, we'll get to them 🌈) and shall include the file access permission bits — in chmod octal or symbolic notation — of the input file, plus the decode_pathname, all so the file can be re-created on another system that conforms to this volume of POSIX.1‐2017. it's giving "pack it up, ship it out" ✨

👑 OPTIONS 👑

The uuencode utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines. yes bestie, the rules of the land.

The following option shall be supported by the implementation:

  • -m — Encode the output using the MIME Base64 algorithm described in STDOUT. If -m is not specified, the historical algorithm described in STDOUT shall be used. so like, -m is the modern glow-up, no -m is the vintage vibe 💜

🦋 OPERANDS 🦋

The following operands shall be supported:

  • decode_pathname — The pathname of the file into which the uudecode utility shall place the decoded file. Specifying a decode_pathname operand of /dev/stdout shall indicate that uudecode is to use standard output. ⚠️ If there are characters in decode_pathname that are not in the portable filename character set, the results are unspecified — so like, don't be chaotic, stay in the portable filename character set fr fr.
  • file — A pathname of the file to be encoded.

🌈 STDIN 🌈

See the INPUT FILES section. (yes, it's a little scavenger hunt, we love a cross-reference 💖)

🍓 INPUT FILES 🍓

Input files can be files of any type. any type!! zero restrictions, main character energy.

💜 ENVIRONMENT VARIABLES 💜

The following environment variables shall affect the execution of uuencode:

  • LANG — Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
  • LC_ALL — If set to a non-empty string value, override the values of all the other internationalization variables. it's the boss of the other locale vars, periodt.
  • LC_CTYPE — 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).
  • LC_MESSAGES — Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
  • NLSPATH — Determine the location of message catalogs for the processing of LC_MESSAGES.

✨ ASYNCHRONOUS EVENTS ✨

Default. (aka, nothing special, carry on 🫶)

🔥 STDOUT 🔥

🎀 uuencode Base64 Algorithm 🎀

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

"begin-base64 %s %s\n", <mode>, <decode_pathname>

and ends with the line:

"====\n"

In both cases, the lines shall have no preceding or trailing <blank> characters. no sneaky spaces bestie, not even one 🙈

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 Table 4-22, uuencode Base64 Values.

🌟 Table 4-22: uuencode Base64 Values 🌟

  • Value 0 → A, 1 → B, 2 → C, 3 → D, 4 → E, 5 → F, 6 → G, 7 → H, 8 → I, 9 → J, 10 → K, 11 → L, 12 → M, 13 → N, 14 → O, 15 → P
  • Value 16 → Q, 17 → R, 18 → S, 19 → T, 20 → U, 21 → V, 22 → W, 23 → X, 24 → Y, 25 → Z, 26 → a, 27 → b, 28 → c, 29 → d, 30 → e, 31 → f
  • Value 32 → g, 33 → h, 34 → i, 35 → j, 36 → k, 37 → l, 38 → m, 39 → n, 40 → o, 41 → p, 42 → q, 43 → r, 44 → s, 45 → t, 46 → u, 47 → v
  • Value 48 → w, 49 → x, 50 → y, 51 → z, 52 → 0, 53 → 1, 54 → 2, 55 → 3, 56 → 4, 57 → 5, 58 → 6, 59 → 7, 60 → 8, 61 → 9, 62 → +, 63 → /
  • Value (pad) → =

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 uudecode). yes, decoding software is chill like that 💅

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. it's the little goodbye wave 👋✨

🌸 uuencode Historical Algorithm 🌸

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

"begin %s %s\n" <mode>, <decode_pathname>

and ends with the line:

"end\n"

In both cases, the lines shall have no preceding or trailing <blank> characters. again with the no sneaky spaces rule 🙈

The algorithm that shall be used for lines in between begin and end 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 'A', would be translated to 'A' in the current codeset, such as 0xc1 if it were EBCDIC.) the way it's just doing character set translation on the fly, obsessed 🧚

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:

0x20 + (( A >> 2                    ) & 0x3F)
0x20 + (((A << 4) | ((B >> 4) & 0xF)) & 0x3F)
0x20 + (((B << 2) | ((C >> 6) & 0x3)) & 0x3F)
0x20 + (( C                         ) & 0x3F)

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. forty-five, remember that number bestie ⭐

💀 STDERR 💀

The standard error shall be used only for diagnostic messages. that's it, that's its whole job.

🎀 OUTPUT FILES 🎀

None. (nope, zero, nada 💖)

🦋 EXTENDED DESCRIPTION 🦋

None. (again: nothing here, we keep it moving ✨)

💜 EXIT STATUS 💜

The following exit values shall be returned:

  • 0 — Successful completion. slay. 👑
  • >0 — An error occurred. 😭

🌈 CONSEQUENCES OF ERRORS 🌈

Default.

The following sections are informative. (yes, that's the actual line, we're not done yet — more parts coming, don't go anywhere bestie 🫶)

💖 APPLICATION USAGE 💖

okay bestie, real talk: this file gets expanded by 35 percent (every three octets turn into four, plus some control info on top), which means it's gonna take longer to transmit. it's giving "worth it but plan accordingly" ✨

so the whole vibe here is that this utility exists to make files you can swap between systems that might have totally different codesets, and to turn binary data into a text file. because of that, the ISO/IEC 646:1991 standard got picked as a midpoint in the algorithm — a known reference point, iykyk. 🎀

and listen, the output from uuencode is a text file on the local system. if the output were in the ISO/IEC 646:1991 standard codeset instead, it might not be a text file — at minimum because the <newline> characters might not match — and then the whole goal of creating a text file would be defeated. 😭 imagine.

if that text file then gets carried over to another machine with the same codeset, it's perfectly compatible with that system's uudecode. slay. but if it's transmitted over a mail system, or sent to a machine with a different codeset, the assumption is that — just like 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. 💫

heads up bestie: that translation only makes sense from the local codeset, NOT if the file has already been put into a ISO/IEC 646:1991 standard representation first. order of operations matters, fr fr.

and one more cute thing: files processed by uuencode can be dropped into pax archives, intermixed with other text files in the same codeset. adorable, flexible, iconic. 💅

🌸 EXAMPLES 🌸

None.

(yeah. nothing. the void. we stan a minimalist king 👑)

🧚 RATIONALE 🧚

okay so story time: a new algorithm was added at the request of the international community, to parallel work in RFC 2045 (MIME). ✨

just like with the historical uuencode format, the Base64 Content-Transfer-Encoding is designed to represent arbitrary sequences of octets in a form that is not humanly readable (sorry bestie, it's not for you, it's for the machines 💀).

a 65-character subset of the ISO/IEC 646:1991 standard is used, which enables 6 bits to be represented per printable character. and the extra 65th character, '=', is there to signify a special processing function. 🎀

this subset has a really important property: it's 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 uuencode algorithm does not share this property — and that's literally the reason a second algorithm was added to the ISO POSIX‐2 standard. periodt. 💅

and why the weird ending? the string "====" was used for termination instead of the end used in the original format, because that original end string could be valid encoded input. can't have ambiguity, no cap. 🦋

fun little history moment: in an early draft, the -m option was named -b (for Base64), but it got renamed to reflect its relationship to RFC 2045. there was also a -u present to invoke the default algorithm, but since that was not historical practice, it was omitted as being unnecessary. we love a glow-up. ✨

oh and if you want the derivation of the /dev/stdout symbol, go see the RATIONALE section in uudecode. it's all connected bestie, it's giving lore. 📖

🔮 FUTURE DIRECTIONS 🔮

None.

(nothing on the horizon. the future is a blank canvas and honestly? vibe. 🌈)

👀 SEE ALSO 👀

  • chmod
  • mailx
  • uudecode

and also: The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines 📚

okay legal bestie moment, gotta say it properly:

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

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 .

aaaand that's the whole page bestie, we made it 🫶 this masterpiece was brought to you by IEEE/The Open Group, dated 2017, and it lives under the name UUENCODE(1POSIX) — go forth and encode, you absolute icon 👑💖✨

📦 where this page comes from