Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstruct.tex @ 6719:faebc1940432 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Understand -Xlinker option.
author Guido van Rossum <guido@python.org>
date Tue, 02 Dec 1997 20:38:11 +0000
parents 9e432468f756
children d03f2e2fbf36
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
1 \section{Built-in Module \sectcode{struct}}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 4878
diff changeset
2 \label{module-struct}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{struct}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 \indexii{C}{structures}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 This module performs conversions between Python values and C
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 structs represented as Python strings. It uses \dfn{format strings}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 (explained below) as compact descriptions of the lay-out of the C
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 structs and the intended conversion to/from Python values.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
2609
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
11 See also built-in module \code{array}.
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
12 \bimodindex{array}
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
13
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 The module defines the following exception and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \renewcommand{\indexsubitem}{(in module struct)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 Exception raised on various occasions; argument is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 describing what is wrong.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 \begin{funcdesc}{pack}{fmt\, v1\, v2\, {\rm \ldots}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 Return a string containing the values
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 \code{\var{v1}, \var{v2}, {\rm \ldots}} packed according to the given
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 format. The arguments must match the values required by the format
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 exactly.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \begin{funcdesc}{unpack}{fmt\, string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 Unpack the string (presumably packed by \code{pack(\var{fmt}, {\rm \ldots})})
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 according to the given format. The result is a tuple even if it
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 contains exactly one item. The string must contain exactly the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 amount of data required by the format (i.e. \code{len(\var{string})} must
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 equal \code{calcsize(\var{fmt})}).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 \begin{funcdesc}{calcsize}{fmt}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 Return the size of the struct (and hence of the string)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 corresponding to the given format.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 Format characters have the following meaning; the conversion between C
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 and Python values should be obvious given their types:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \begin{tableiii}{|c|l|l|}{samp}{Format}{C}{Python}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \lineiii{x}{pad byte}{no value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \lineiii{c}{char}{string of length 1}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 \lineiii{b}{signed char}{integer}
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
49 \lineiii{B}{unsigned char}{integer}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 \lineiii{h}{short}{integer}
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
51 \lineiii{H}{unsigned short}{integer}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \lineiii{i}{int}{integer}
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
53 \lineiii{I}{unsigned int}{integer}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \lineiii{l}{long}{integer}
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
55 \lineiii{L}{unsigned long}{integer}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 \lineiii{f}{float}{float}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 \lineiii{d}{double}{float}
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
58 \lineiii{s}{char[]}{string}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 \end{tableiii}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
61 A format character may be preceded by an integral repeat count; e.g.\
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 the format string \code{'4h'} means exactly the same as \code{'hhhh'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63
6167
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
64 Whitespace characters between formats are ignored; a count and its
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
65 format must not contain whitespace though.
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
66
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
67 For the \code{'s'} format character, the count is interpreted as the
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
68 size of the string, not a repeat count like for the other format
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
69 characters; e.g. \code{'10s'} means a single 10-byte string, while
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
70 \code{'10c'} means 10 characters. For packing, the string is
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
71 truncated or padded with null bytes as appropriate to make it fit.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
72 For unpacking, the resulting string always has exactly the specified
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
73 number of bytes. As a special case, \code{'0s'} means a single, empty
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
74 string (while \code{'0c'} means 0 characters).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
75
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
76 For the \code{'I'} and \code{'L'} format characters, the return
4878
a9e7e0ccaa4a 'I' and 'L' now always return a Python long.
Guido van Rossum <guido@python.org>
parents: 4866
diff changeset
77 value is a Python long integer.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
78
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
79 By default, C numbers are represented in the machine's native format
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
80 and byte order, and properly aligned by skipping pad bytes if
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
81 necessary (according to the rules used by the C compiler).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
82
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
83 Alternatively, the first character of the format string can be used to
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
84 indicate the byte order, size and alignment of the packed data,
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
85 according to the following table:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
86
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
87 \begin{tableiii}{|c|l|l|}{samp}{Character}{Byte order}{Size and alignment}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
88 \lineiii{@}{native}{native}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
89 \lineiii{=}{native}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
90 \lineiii{<}{little-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
91 \lineiii{>}{big-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
92 \lineiii{!}{network (= big-endian)}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
93 \end{tableiii}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
94
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
95 If the first character is not one of these, \code{'@'} is assumed.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
96
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
97 Native byte order is big-endian or little-endian, depending on the
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
98 host system (e.g. Motorola and Sun are big-endian; Intel and DEC are
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
99 little-endian).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
100
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
101 Native size and alignment are determined using the C compiler's sizeof
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
102 expression. This is always combined with native byte order.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
103
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
104 Standard size and alignment are as follows: no alignment is required
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
105 for any type (so you have to use pad bytes); short is 2 bytes; int and
4866
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
106 long are 4 bytes. Float and double are 32-bit and 64-bit IEEE floating
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
107 point numbers, respectively.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
108
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
109 Note the difference between \code{'@'} and \code{'='}: both use native
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
110 byte order, but the size and alignment of the latter is standardized.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
111
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
112 The form \code{'!'} is available for those poor souls who claim they
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
113 can't remember whether network byte order is big-endian or
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
114 little-endian.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
115
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
116 There is no way to indicate non-native byte order (i.e. force
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
117 byte-swapping); use the appropriate choice of \code{'<'} or
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
118 \code{'>'}.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
119
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
120 Examples (all using native byte order, size and alignment, on a
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
121 big-endian machine):
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \bcode\begin{verbatim}
4866
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
124 >>> from struct import *
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
125 >>> pack('hhl', 1, 2, 3)
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
126 '\000\001\000\002\000\000\000\003'
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
127 >>> unpack('hhl', '\000\001\000\002\000\000\000\003')
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
128 (1, 2, 3)
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
129 >>> calcsize('hhl')
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
130 8
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
131 >>>
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 \end{verbatim}\ecode
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 4878
diff changeset
133 %
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 Hint: to align the end of a structure to the alignment requirement of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 a particular type, end the format with the code for that type with a
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
136 repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
137 pad bytes at the end, assuming longs are aligned on 4-byte boundaries.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
138 (This only works when native size and alignment are in effect;
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
139 standard size and alignment does not enforce any alignment.)