summaryrefslogtreecommitdiffstats
path: root/Doc/libxdrlib.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/libxdrlib.tex')
-rw-r--r--Doc/libxdrlib.tex232
1 files changed, 0 insertions, 232 deletions
diff --git a/Doc/libxdrlib.tex b/Doc/libxdrlib.tex
deleted file mode 100644
index 56459f8..0000000
--- a/Doc/libxdrlib.tex
+++ /dev/null
@@ -1,232 +0,0 @@
-\section{Standard Module \module{xdrlib}}
-\label{module-xdrlib}
-\stmodindex{xdrlib}
-\index{XDR}
-\index{External Data Representation}
-
-
-
-The \module{xdrlib} module supports the External Data Representation
-Standard as described in \rfc{1014}, written by Sun Microsystems,
-Inc. June 1987. It supports most of the data types described in the
-RFC.
-
-The \module{xdrlib} module defines two classes, one for packing
-variables into XDR representation, and another for unpacking from XDR
-representation. There are also two exception classes.
-
-\begin{classdesc}{Packer}{}
-\class{Packer} is the class for packing data into XDR representation.
-The \class{Packer} class is instantiated with no arguments.
-\end{classdesc}
-
-\begin{classdesc}{Unpacker}{data}
-\code{Unpacker} is the complementary class which unpacks XDR data
-values from a string buffer. The input buffer is given as
-\var{data}.
-\end{classdesc}
-
-
-\subsection{Packer Objects}
-\label{xdr-packer-objects}
-
-\class{Packer} instances have the following methods:
-
-\begin{methoddesc}[Packer]{get_buffer}{}
-Returns the current pack buffer as a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{reset}{}
-Resets the pack buffer to the empty string.
-\end{methoddesc}
-
-In general, you can pack any of the most common XDR data types by
-calling the appropriate \code{pack_\var{type}()} method. Each method
-takes a single argument, the value to pack. The following simple data
-type packing methods are supported: \method{pack_uint()},
-\method{pack_int()}, \method{pack_enum()}, \method{pack_bool()},
-\method{pack_uhyper()}, and \method{pack_hyper()}.
-
-\begin{methoddesc}[Packer]{pack_float}{value}
-Packs the single-precision floating point number \var{value}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_double}{value}
-Packs the double-precision floating point number \var{value}.
-\end{methoddesc}
-
-The following methods support packing strings, bytes, and opaque data:
-
-\begin{methoddesc}[Packer]{pack_fstring}{n, s}
-Packs a fixed length string, \var{s}. \var{n} is the length of the
-string but it is \emph{not} packed into the data buffer. The string
-is padded with null bytes if necessary to guaranteed 4 byte alignment.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_fopaque}{n, data}
-Packs a fixed length opaque data stream, similarly to
-\method{pack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_string}{s}
-Packs a variable length string, \var{s}. The length of the string is
-first packed as an unsigned integer, then the string data is packed
-with \method{pack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_opaque}{data}
-Packs a variable length opaque data string, similarly to
-\method{pack_string()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_bytes}{bytes}
-Packs a variable length byte stream, similarly to \method{pack_string()}.
-\end{methoddesc}
-
-The following methods support packing arrays and lists:
-
-\begin{methoddesc}[Packer]{pack_list}{list, pack_item}
-Packs a \var{list} of homogeneous items. This method is useful for
-lists with an indeterminate size; i.e. the size is not available until
-the entire list has been walked. For each item in the list, an
-unsigned integer \code{1} is packed first, followed by the data value
-from the list. \var{pack_item} is the function that is called to pack
-the individual item. At the end of the list, an unsigned integer
-\code{0} is packed.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item}
-Packs a fixed length list (\var{array}) of homogeneous items. \var{n}
-is the length of the list; it is \emph{not} packed into the buffer,
-but a \exception{ValueError} exception is raised if
-\code{len(\var{array})} is not equal to \var{n}. As above,
-\var{pack_item} is the function used to pack each element.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_array}{list, pack_item}
-Packs a variable length \var{list} of homogeneous items. First, the
-length of the list is packed as an unsigned integer, then each element
-is packed as in \method{pack_farray()} above.
-\end{methoddesc}
-
-
-\subsection{Unpacker Objects}
-\label{xdr-unpacker-objects}
-
-The \class{Unpacker} class offers the following methods:
-
-\begin{methoddesc}[Unpacker]{reset}{data}
-Resets the string buffer with the given \var{data}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{get_position}{}
-Returns the current unpack position in the data buffer.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{set_position}{position}
-Sets the data buffer unpack position to \var{position}. You should be
-careful about using \method{get_position()} and \method{set_position()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{get_buffer}{}
-Returns the current unpack data buffer as a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{done}{}
-Indicates unpack completion. Raises an \exception{Error} exception
-if all of the data has not been unpacked.
-\end{methoddesc}
-
-In addition, every data type that can be packed with a \class{Packer},
-can be unpacked with an \class{Unpacker}. Unpacking methods are of the
-form \code{unpack_\var{type}()}, and take no arguments. They return the
-unpacked object.
-
-\begin{methoddesc}[Unpacker]{unpack_float}{}
-Unpacks a single-precision floating point number.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_double}{}
-Unpacks a double-precision floating point number, similarly to
-\method{unpack_float()}.
-\end{methoddesc}
-
-In addition, the following methods unpack strings, bytes, and opaque
-data:
-
-\begin{methoddesc}[Unpacker]{unpack_fstring}{n}
-Unpacks and returns a fixed length string. \var{n} is the number of
-characters expected. Padding with null bytes to guaranteed 4 byte
-alignment is assumed.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_fopaque}{n}
-Unpacks and returns a fixed length opaque data stream, similarly to
-\method{unpack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_string}{}
-Unpacks and returns a variable length string. The length of the
-string is first unpacked as an unsigned integer, then the string data
-is unpacked with \method{unpack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_opaque}{}
-Unpacks and returns a variable length opaque data string, similarly to
-\method{unpack_string()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_bytes}{}
-Unpacks and returns a variable length byte stream, similarly to
-\method{unpack_string()}.
-\end{methoddesc}
-
-The following methods support unpacking arrays and lists:
-
-\begin{methoddesc}[Unpacker]{unpack_list}{unpack_item}
-Unpacks and returns a list of homogeneous items. The list is unpacked
-one element at a time
-by first unpacking an unsigned integer flag. If the flag is \code{1},
-then the item is unpacked and appended to the list. A flag of
-\code{0} indicates the end of the list. \var{unpack_item} is the
-function that is called to unpack the items.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item}
-Unpacks and returns (as a list) a fixed length array of homogeneous
-items. \var{n} is number of list elements to expect in the buffer.
-As above, \var{unpack_item} is the function used to unpack each element.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_array}{unpack_item}
-Unpacks and returns a variable length \var{list} of homogeneous items.
-First, the length of the list is unpacked as an unsigned integer, then
-each element is unpacked as in \method{unpack_farray()} above.
-\end{methoddesc}
-
-
-\subsection{Exceptions}
-\nodename{xdr-exceptions}
-
-Exceptions in this module are coded as class instances:
-
-\begin{excdesc}{Error}
-The base exception class. \exception{Error} has a single public data
-member \member{msg} containing the description of the error.
-\end{excdesc}
-
-\begin{excdesc}{ConversionError}
-Class derived from \exception{Error}. Contains no additional instance
-variables.
-\end{excdesc}
-
-Here is an example of how you would catch one of these exceptions:
-
-\begin{verbatim}
-import xdrlib
-p = xdrlib.Packer()
-try:
- p.pack_double(8.01)
-except xdrlib.ConversionError, instance:
- print 'packing the double failed:', instance.msg
-\end{verbatim}