usr.bin/uuencode/uuencode.5

   1 .\"     $NetBSD: uuencode.5,v 1.10 2008/08/23 16:32:50 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)uuencode.format.5   8.2 (Berkeley) 1/12/94
  31 .\"
  32 .Dd April 9, 1997
  33 .Dt UUENCODE 5
  34 .Os
  35 .Sh NAME
  36 .Nm uuencode
  37 .Nd format of an encoded uuencode file
  38 .Sh DESCRIPTION
  39 Files output by
  40 .Xr uuencode 1
  41 consist of a header line,
  42 followed by a number of body lines,
  43 and a trailer line.
  44 The
  45 .Xr uudecode 1
  46 command
  47 will ignore any lines preceding the header or
  48 following the trailer.
  49 Lines preceding a header must not, of course,
  50 look like a header.
  51 .Pp
  52 The header line starts with the word
  53 .Dq begin ,
  54 a space,
  55 a file mode (in octal),
  56 a space,
  57 and finally a string which names the file being encoded.
  58 .Pp
  59 The central engine of
  60 .Xr uuencode 1
  61 is a six-bit encoding function which outputs an
  62 .Tn ASCII
  63 character.
  64 The six bits to be encoded are treated as a small integer and added
  65 with the
  66 .Tn ASCII
  67 value for the space character (octal 40).
  68 The result is a printable
  69 .Tn ASCII
  70 character.
  71 In the case where all six bits to be encoded are zero,
  72 the
  73 .Tn ASCII
  74 backquote character \` (octal 140) is emitted instead of what
  75 would normally be a space.
  76 .Pp
  77 The body of an encoded file consists of one or more lines,
  78 each of which may be a maximum of 86 characters long (including the trailing
  79 newline).
  80 Each line represents an encoded chunk of data from the input file and begins
  81 with a byte count,
  82 followed by encoded bytes,
  83 followed by a newline.
  84 .Pp
  85 The byte count is a six-bit integer encoded with the above function,
  86 representing the number of bytes encoded in the rest of the line.
  87 The method used to encode the data expands its size by
  88 133% (described below).
  89 Therefore it is important to note that the byte count describes the size of
  90 the chunk of data before it is encoded, not afterwards.
  91 The six bit size of this number effectively limits the number of bytes
  92 that can be encoded in each line to a maximum of 63.
  93 While
  94 .Xr uuencode 1
  95 will not encode more than 45 bytes per line,
  96 .Xr uudecode 1
  97 will tolerate the maximum line size.
  98 .Pp
  99 The remaining characters in the line represent the data of the input
 100 file encoded as follows.
 101 Input data are broken into groups of three eight-bit bytes,
 102 which are then interpreted together as a 24-bit block.
 103 The first bit of the block is the highest order bit of the first character,
 104 and the last is the lowest order bit of the third character.
 105 This block is then broken into four six-bit integers which are encoded one by
 106 one starting from the first bit of the block.
 107 The result is a four character
 108 .Tn ASCII
 109 string for every three bytes of input data.
 110 .Pp
 111 Encoded lines of data continue in this manner until the input file is
 112 exhausted.
 113 The end of the body is signaled by an encoded line with a byte count
 114 of zero (the
 115 .Tn ASCII
 116 backquote character \`).
 117 .Pp
 118 Obviously, not every input file will be a multiple of three bytes in size.
 119 In these cases,
 120 .Xr uuencode 1
 121 will pad the remaining one or two bytes of data with garbage bytes until
 122 a three byte group is created.
 123 The byte count in a line containing
 124 garbage padding will reflect the actual number of bytes encoded, making
 125 it possible to convey how many bytes are garbage.
 126 .Pp
 127 The trailer line consists of
 128 .Dq end
 129 on a line by itself.
 130 .Sh SEE ALSO
 131 .Xr mail 1 ,
 132 .Xr uucp 1 ,
 133 .Xr uudecode 1 ,
 134 .Xr uuencode 1 ,
 135 .Xr ascii 7
 136 .Sh HISTORY
 137 The
 138 .Nm
 139 file format appeared in
 140 .Bx 4.0 .
 141 .Sh BUGS
 142 The interpretation of the
 143 .Nm
 144 format relies on properties of the
 145 .Tn ASCII
 146 character set and may not work correctly on non-ASCII systems.