Patch by Greg Stein to document the 'P' flag.

1 files changed, 17 insertions, 0 deletions

diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
index be7d80b..14627b6 100644
--- a/Doc/lib/libstruct.tex
+++ b/Doc/lib/libstruct.tex
@@ -57,6 +57,7 @@ and Python values should be obvious given their types:
   \lineiii{d}{double}{float}
   \lineiii{s}{char[]}{string}
   \lineiii{p}{char[]}{string}
+  \lineiii{P}{void *}{integer}
 \end{tableiii}
 
 A format character may be preceded by an integral repeat count; e.g.\
@@ -85,6 +86,15 @@ that exactly enough bytes are used to satisfy the count.
 For the \character{I} and \character{L} format characters, the return
 value is a Python long integer.
 
+For the \character{P} format character, the return value is a Python
+integer or long integer, depending on the size needed to hold a
+pointer when it has been cast to an integer type.  A NULL pointer will
+always be returned as the Python integer 0. When packing pointer-sized
+values, Python integer or long integer objects may be used.  For
+example, the Alpha and Merced processors use 64-bit pointer values,
+meaning a Python long integer will be used to hold the pointer; other
+platforms use 32-bit pointers and will use a Python integer.
+
 By default, 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).
@@ -126,6 +136,13 @@ There is no way to indicate non-native byte order (i.e. force
 byte-swapping); use the appropriate choice of \character{<} or
 \character{>}.
 
+The \character{P} format character is only available for the native
+byte ordering (selected as the default or with the \character{@} byte
+order character). The byte order character \character{=} chooses to
+use little- or big-endian ordering based on the host system. The
+struct module does not interpret this as native ordering, so the
+\character{P} format is not available.
+
 Examples (all using native byte order, size and alignment, on a
 big-endian machine):