usr.bin/bintrans/bintrans.1

   1 .\" Copyright (c) 1980, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)uuencode.1    8.1 (Berkeley) 6/6/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd April 18, 2022
  32 .Dt BINTRANS 1
  33 .Os
  34 .Sh NAME
  35 .Nm bintrans ,
  36 .Nm uuencode ,
  37 .Nm uudecode ,
  38 .Nm b64encode ,
  39 .Nm b64decode
  40 .Nd encode/decode a binary file
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op algorithm
  44 .Op ...
  45 .Nm uuencode
  46 .Op Fl m
  47 .Op Fl r
  48 .Op Fl o Ar output_file
  49 .Op Ar file
  50 .Ar name
  51 .Nm uudecode
  52 .Op Fl cimprs
  53 .Op Ar
  54 .Nm uudecode
  55 .Op Fl i
  56 .Fl o Ar output_file
  57 .Nm b64encode
  58 .Op Fl r
  59 .Op Fl w Ar column
  60 .Op Fl o Ar output_file
  61 .Op Ar file
  62 .Ar name
  63 .Nm b64decode
  64 .Op Fl cimprs
  65 .Op Ar
  66 .Nm b64decode
  67 .Op Fl i
  68 .Fl o Ar output_file
  69 .Op Ar file
  70 .Nm base64
  71 .Op Fl d
  72 .Op Fl w Ar column
  73 .Op Ar file
  74 .Sh DESCRIPTION
  75 The
  76 .Nm uuencode
  77 and
  78 .Nm uudecode
  79 utilities are used to transmit binary files over transmission mediums
  80 that do not support other than simple
  81 .Tn ASCII
  82 data.
  83 The
  84 .Nm b64encode
  85 utility is synonymous with
  86 .Nm uuencode
  87 with the
  88 .Fl m
  89 flag specified.
  90 The
  91 .Nm b64decode
  92 utility is synonymous with
  93 .Nm uudecode
  94 with the
  95 .Fl m
  96 flag specified.
  97 .Pp
  98 The
  99 .Nm base64
 100 utility acts as a base64 decoder when passed the
 101 .Fl -decode
 102 .Po or
 103 .Fl d
 104 .Pc
 105 flag and as a base64 encoder otherwise.
 106 As a decoder it only accepts raw base64 input
 107 and as an encoder it does not produce the framing lines.
 108 .Nm base64
 109 reads standard input or
 110 .Ar file
 111 if it is provided and writes to standard output.
 112 Options
 113 .Fl -wrap
 114 .Po or
 115 .Fl w
 116 .Pc
 117 and
 118 .Fl -ignore-garbage
 119 .Po or
 120 .Fl i
 121 .Pc
 122 are accepted for compatibility with GNU base64,
 123 but the latter is unimplemented and silently ignored.
 124 .Pp
 125 The
 126 .Nm uuencode
 127 utility reads
 128 .Ar file
 129 (or by default the standard input) and writes an encoded version
 130 to the standard output, or
 131 .Ar output_file
 132 if one has been specified.
 133 The encoding uses only printing
 134 .Tn ASCII
 135 characters and includes the
 136 mode of the file and the operand
 137 .Ar name
 138 for use by
 139 .Nm uudecode .
 140 .Pp
 141 The
 142 .Nm uudecode
 143 utility transforms
 144 .Em uuencoded
 145 files (or by default, the standard input) into the original form.
 146 The resulting file is named either
 147 .Ar name
 148 or (depending on options passed to
 149 .Nm uudecode )
 150 .Ar output_file
 151 and will have the mode of the original file except that setuid
 152 and execute bits are not retained.
 153 The
 154 .Nm uudecode
 155 utility ignores any leading and trailing lines.
 156 .Pp
 157 The following options are available for
 158 .Nm uuencode :
 159 .Bl -tag -width ident
 160 .It Fl m
 161 Use the Base64 method of encoding, rather than the traditional
 162 .Nm uuencode
 163 algorithm.
 164 .It Fl r
 165 Produce raw output by excluding the initial and final framing lines.
 166 .It Fl o Ar output_file
 167 Output to
 168 .Ar output_file
 169 instead of standard output.
 170 .El
 171 .Pp
 172 The following options are available for
 173 .Nm uudecode :
 174 .Bl -tag -width ident
 175 .It Fl c
 176 Decode more than one uuencoded file from
 177 .Ar file
 178 if possible.
 179 .It Fl i
 180 Do not overwrite files.
 181 .It Fl m
 182 When used with the
 183 .Fl r
 184 flag, decode Base64 input instead of traditional
 185 .Nm uuencode
 186 input.
 187 Without
 188 .Fl r
 189 it has no effect.
 190 .It Fl o Ar output_file
 191 Output to
 192 .Ar output_file
 193 instead of any pathname contained in the input data.
 194 .It Fl p
 195 Decode
 196 .Ar file
 197 and write output to standard output.
 198 .It Fl r
 199 Decode raw (or broken) input, which is missing the initial and
 200 possibly the final framing lines.
 201 The input is assumed to be in the traditional
 202 .Nm uuencode
 203 encoding, but if the
 204 .Fl m
 205 flag is used, or if the utility is invoked as
 206 .Nm b64decode ,
 207 then the input is assumed to be in Base64 format.
 208 .It Fl s
 209 Do not strip output pathname to base filename.
 210 By default
 211 .Nm uudecode
 212 deletes any prefix ending with the last slash '/' for security
 213 reasons.
 214 .El
 215 .Pp
 216 Additionally,
 217 .Nm b64encode
 218 accepts the following option:
 219 .Bl -tag -width ident
 220 .It Fl w Ar column
 221 Wrap encoded output after
 222 .Ar column .
 223 .El
 224 .Pp
 225 .Nm
 226 is a generic utility that can run
 227 any of the aforementioned encoders and decoders.
 228 It can also run algorithms that are not available
 229 through a dedicated program:
 230 .Pp
 231 .Nm qp
 232 is a quoted-printable converter
 233 and accepts the following options:
 234 .Bl -tag -width ident
 235 .It Fl u
 236 Decode.
 237 .It Fl o Ar output_file
 238 Output to
 239 .Ar output_file
 240 instead of standard output.
 241 .Sh EXAMPLES
 242 The following example packages up a source tree, compresses it,
 243 uuencodes it and mails it to a user on another system.
 244 When
 245 .Nm uudecode
 246 is run on the target system, the file ``src_tree.tar.Z'' will be
 247 created which may then be uncompressed and extracted into the original
 248 tree.
 249 .Pp
 250 .Bd -literal -offset indent -compact
 251 tar cf \- src_tree \&| compress \&|
 252 uuencode src_tree.tar.Z \&| mail user@example.com
 253 .Ed
 254 .Pp
 255 The following example unpacks all uuencoded
 256 files from your mailbox into your current working directory.
 257 .Pp
 258 .Bd -literal -offset indent -compact
 259 uudecode -c < $MAIL
 260 .Ed
 261 .Pp
 262 The following example extracts a compressed tar
 263 archive from your mailbox
 264 .Pp
 265 .Bd -literal -offset indent -compact
 266 uudecode -o /dev/stdout < $MAIL | zcat | tar xfv -
 267 .Ed
 268 .Sh SEE ALSO
 269 .Xr basename 1 ,
 270 .Xr compress 1 ,
 271 .Xr mail 1 ,
 272 .Xr uucp 1 Pq Pa ports/net/freebsd-uucp ,
 273 .Xr uuencode 5
 274 .Sh HISTORY
 275 The
 276 .Nm uudecode
 277 and
 278 .Nm uuencode
 279 utilities appeared in
 280 .Bx 4.0 .
 281 .Sh BUGS
 282 Files encoded using the traditional algorithm are expanded by 35% (3
 283 bytes become 4 plus control information).