cpython / Doc / libstruct.tex

Full commit
\section{Built-in module \sectcode{struct}}

This module performs conversions between Python values and C
structs represented as Python strings.  It uses \dfn{format strings}
(explained below) as compact descriptions of the lay-out of the C
structs and the intended conversion to/from Python values.

The module defines the following exception and functions:

\renewcommand{\indexsubitem}{(in module struct)}
  Exception raised on various occasions; argument is a string
  describing what is wrong.

\begin{funcdesc}{pack}{fmt\, v1\, v2\, {\rm \ldots}}
  Return a string containing the values
  \code{\var{v1}, \var{v2}, {\rm \ldots}} packed according to the given
  format.  The arguments must match the values required by the format

\begin{funcdesc}{unpack}{fmt\, string}
  Unpack the string (presumably packed by \code{pack(\var{fmt}, {\rm \ldots})})
  according to the given format.  The result is a tuple even if it
  contains exactly one item.  The string must contain exactly the
  amount of data required by the format (i.e.  \code{len(\var{string})} must
  equal \code{calcsize(\var{fmt})}).

  Return the size of the struct (and hence of the string)
  corresponding to the given format.

Format characters have the following meaning; the conversion between C
and Python values should be obvious given their types:

  \lineiii{x}{pad byte}{no value}
  \lineiii{c}{char}{string of length 1}
  \lineiii{b}{signed char}{integer}

A format character may be preceded by an integral repeat count; e.g.
the format string \code{'4h'} means exactly the same as \code{'hhhh'}.

C numbers are represented in the machine's native format and byte
order, and properly aligned by skipping pad bytes if necessary
(according to the rules used by the C compiler).

Examples (all on a big-endian machine):

pack('hhl', 1, 2, 3) == '\000\001\000\002\000\000\000\003'
unpack('hhl', '\000\001\000\002\000\000\000\003') == (1, 2, 3)
calcsize('hhl') == 8

Hint: to align the end of a structure to the alignment requirement of
a particular type, end the format with the code for that type with a
repeat count of zero, e.g. the format \code{'llh0l'} specifies two
pad bytes at the end, assuming longs are aligned on 4-byte boundaries.

(More format characters are planned, e.g. \code{'s'} for character
arrays, upper case for unsigned variants, and a way to specify the
byte order, which is useful for [de]constructing network packets and
reading/writing portable binary file formats like TIFF and AIFF.)