summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libuu.tex
blob: 53354f23e3f0202d94bd2c761b8784ddbabd3e71 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
\section{\module{uu} ---
         Encode and decode uuencode files}

\declaremodule{standard}{uu}
\modulesynopsis{Encode and decode files in uuencode format.}
\moduleauthor{Lance Ellinghouse}{}


This module encodes and decodes files in uuencode format, allowing
arbitrary binary data to be transferred over ASCII-only connections.
Wherever a file argument is expected, the methods accept a file-like
object.  For backwards compatibility, a string containing a pathname
is also accepted, and the corresponding file will be opened for
reading and writing; the pathname \code{'-'} is understood to mean the
standard input or output.  However, this interface is deprecated; it's
better for the caller to open the file itself, and be sure that, when
required, the mode is \code{'rb'} or \code{'wb'} on Windows.

This code was contributed by Lance Ellinghouse, and modified by Jack
Jansen.
\index{Jansen, Jack}
\index{Ellinghouse, Lance}

The \module{uu} module defines the following functions:

\begin{funcdesc}{encode}{in_file, out_file\optional{, name\optional{, mode}}}
  Uuencode file \var{in_file} into file \var{out_file}.  The uuencoded
  file will have the header specifying \var{name} and \var{mode} as
  the defaults for the results of decoding the file. The default
  defaults are taken from \var{in_file}, or \code{'-'} and \code{0666}
  respectively.
\end{funcdesc}

\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode}}}
  This call decodes uuencoded file \var{in_file} placing the result on
  file \var{out_file}. If \var{out_file} is a pathname, \var{mode} is
  used to set the permission bits if the file must be
  created. Defaults for \var{out_file} and \var{mode} are taken from
  the uuencode header.  However, if the file specified in the header
  already exists, a \exception{uu.Error} is raised.
\end{funcdesc}

\begin{excclassdesc}{Error}{}
  Subclass of \exception{Exception}, this can be raised by
  \function{uu.decode()} under various situations, such as described
  above, but also including a badly formated header, or truncated
  input file.
\end{excclassdesc}

\begin{seealso}
  \seemodule{binascii}{Support module containing \ASCII-to-binary
                       and binary-to-\ASCII{} conversions.}
\end{seealso}