Doc/lib/libstruct.tex

   1 \section{\module{struct} ---
   2          Interpret strings as packed binary data}
   3 \declaremodule{builtin}{struct}
   4
   5 \modulesynopsis{Interpret strings as packed binary data.}
   6
   7 \indexii{C}{structures}
   8 \indexiii{packing}{binary}{data}
   9
  10 This module performs conversions between Python values and C
  11 structs represented as Python strings.  It uses \dfn{format strings}
  12 (explained below) as compact descriptions of the lay-out of the C
  13 structs and the intended conversion to/from Python values.  This can
  14 be used in handling binary data stored in files or from network
  15 connections, among other sources.
  16
  17 The module defines the following exception and functions:
  18
  19
  20 \begin{excdesc}{error}
  21   Exception raised on various occasions; argument is a string
  22   describing what is wrong.
  23 \end{excdesc}
  24
  25 \begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}}
  26   Return a string containing the values
  27   \code{\var{v1}, \var{v2}, \textrm{\ldots}} packed according to the given
  28   format.  The arguments must match the values required by the format
  29   exactly.
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{unpack}{fmt, string}
  33   Unpack the string (presumably packed by \code{pack(\var{fmt},
  34   \textrm{\ldots})}) according to the given format.  The result is a
  35   tuple even if it contains exactly one item.  The string must contain
  36   exactly the amount of data required by the format (i.e.
  37   \code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{calcsize}{fmt}
  41   Return the size of the struct (and hence of the string)
  42   corresponding to the given format.
  43 \end{funcdesc}
  44
  45 Format characters have the following meaning; the conversion between
  46 C and Python values should be obvious given their types:
  47
  48 \begin{tableiv}{c|l|l|c}{samp}{Format}{C Type}{Python}{Notes}
  49   \lineiv{x}{pad byte}{no value}{}
  50   \lineiv{c}{\ctype{char}}{string of length 1}{}
  51   \lineiv{b}{\ctype{signed char}}{integer}{}
  52   \lineiv{B}{\ctype{unsigned char}}{integer}{}
  53   \lineiv{h}{\ctype{short}}{integer}{}
  54   \lineiv{H}{\ctype{unsigned short}}{integer}{}
  55   \lineiv{i}{\ctype{int}}{integer}{}
  56   \lineiv{I}{\ctype{unsigned int}}{long}{(1)}
  57   \lineiv{l}{\ctype{long}}{integer}{}
  58   \lineiv{L}{\ctype{unsigned long}}{long}{}
  59   \lineiv{f}{\ctype{float}}{float}{}
  60   \lineiv{d}{\ctype{double}}{float}{}
  61   \lineiv{s}{\ctype{char[]}}{string}{}
  62   \lineiv{p}{\ctype{char[]}}{string}{}
  63   \lineiv{P}{\ctype{void *}}{integer}{}
  64 \end{tableiv}
  65
  66 \noindent
  67 Notes:
  68
  69 \begin{description}
  70 \item[(1)]
  71   The \character{I} conversion code will convert to a Python long if
  72   the C \ctype{int} is the same size as a C \ctype{long}, which is
  73   typical on most modern systems.  If a C \ctype{int} is smaller than
  74   a C \ctype{long}, an Python integer will be created instead.
  75 \end{description}
  76
  77
  78 A format character may be preceded by an integral repeat count;
  79 e.g.\ the format string \code{'4h'} means exactly the same as
  80 \code{'hhhh'}.
  81
  82 Whitespace characters between formats are ignored; a count and its
  83 format must not contain whitespace though.
  84
  85 For the \character{s} format character, the count is interpreted as the
  86 size of the string, not a repeat count like for the other format
  87 characters; e.g. \code{'10s'} means a single 10-byte string, while
  88 \code{'10c'} means 10 characters.  For packing, the string is
  89 truncated or padded with null bytes as appropriate to make it fit.
  90 For unpacking, the resulting string always has exactly the specified
  91 number of bytes.  As a special case, \code{'0s'} means a single, empty
  92 string (while \code{'0c'} means 0 characters).
  93
  94 The \character{p} format character can be used to encode a Pascal
  95 string.  The first byte is the length of the stored string, with the
  96 bytes of the string following.  If count is given, it is used as the
  97 total number of bytes used, including the length byte.  If the string
  98 passed in to \function{pack()} is too long, the stored representation
  99 is truncated.  If the string is too short, padding is used to ensure
 100 that exactly enough bytes are used to satisfy the count.
 101
 102 For the \character{I} and \character{L} format characters, the return
 103 value is a Python long integer.
 104
 105 For the \character{P} format character, the return value is a Python
 106 integer or long integer, depending on the size needed to hold a
 107 pointer when it has been cast to an integer type.  A \NULL{} pointer will
 108 always be returned as the Python integer \code{0}. When packing pointer-sized
 109 values, Python integer or long integer objects may be used.  For
 110 example, the Alpha and Merced processors use 64-bit pointer values,
 111 meaning a Python long integer will be used to hold the pointer; other
 112 platforms use 32-bit pointers and will use a Python integer.
 113
 114 By default, C numbers are represented in the machine's native format
 115 and byte order, and properly aligned by skipping pad bytes if
 116 necessary (according to the rules used by the C compiler).
 117
 118 Alternatively, the first character of the format string can be used to
 119 indicate the byte order, size and alignment of the packed data,
 120 according to the following table:
 121
 122 \begin{tableiii}{c|l|l}{samp}{Character}{Byte order}{Size and alignment}
 123   \lineiii{@}{native}{native}
 124   \lineiii{=}{native}{standard}
 125   \lineiii{<}{little-endian}{standard}
 126   \lineiii{>}{big-endian}{standard}
 127   \lineiii{!}{network (= big-endian)}{standard}
 128 \end{tableiii}
 129
 130 If the first character is not one of these, \character{@} is assumed.
 131
 132 Native byte order is big-endian or little-endian, depending on the
 133 host system (e.g. Motorola and Sun are big-endian; Intel and DEC are
 134 little-endian).
 135
 136 Native size and alignment are determined using the C compiler's
 137 \keyword{sizeof} expression.  This is always combined with native byte
 138 order.
 139
 140 Standard size and alignment are as follows: no alignment is required
 141 for any type (so you have to use pad bytes); \ctype{short} is 2 bytes;
 142 \ctype{int} and \ctype{long} are 4 bytes.  \ctype{float} and
 143 \ctype{double} are 32-bit and 64-bit IEEE floating point numbers,
 144 respectively.
 145
 146 Note the difference between \character{@} and \character{=}: both use
 147 native byte order, but the size and alignment of the latter is
 148 standardized.
 149
 150 The form \character{!} is available for those poor souls who claim they
 151 can't remember whether network byte order is big-endian or
 152 little-endian.
 153
 154 There is no way to indicate non-native byte order (i.e. force
 155 byte-swapping); use the appropriate choice of \character{<} or
 156 \character{>}.
 157
 158 The \character{P} format character is only available for the native
 159 byte ordering (selected as the default or with the \character{@} byte
 160 order character). The byte order character \character{=} chooses to
 161 use little- or big-endian ordering based on the host system. The
 162 struct module does not interpret this as native ordering, so the
 163 \character{P} format is not available.
 164
 165 Examples (all using native byte order, size and alignment, on a
 166 big-endian machine):
 167
 168 \begin{verbatim}
 169 >>> from struct import *
 170 >>> pack('hhl', 1, 2, 3)
 171 '\000\001\000\002\000\000\000\003'
 172 >>> unpack('hhl', '\000\001\000\002\000\000\000\003')
 173 (1, 2, 3)
 174 >>> calcsize('hhl')
 175 8
 176 \end{verbatim}
 177
 178 Hint: to align the end of a structure to the alignment requirement of
 179 a particular type, end the format with the code for that type with a
 180 repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
 181 pad bytes at the end, assuming longs are aligned on 4-byte boundaries.
 182 This only works when native size and alignment are in effect;
 183 standard size and alignment does not enforce any alignment.
 184
 185 \begin{seealso}
 186   \seemodule{array}{Packed binary storage of homogeneous data.}
 187   \seemodule{xdrlib}{Packing and unpacking of XDR data.}
 188 \end{seealso}