--- Python-Docs-2.4/./lib/libctypes.tex	1970-01-01 09:00:00.000000000 +0900
+++ Python-Docs-2.5/./lib/libctypes.tex	2006-08-17 03:02:11.000000000 +0900
@@ -0,0 +1,2444 @@
+\ifx\locallinewidth\undefined\newlength{\locallinewidth}\fi
+\setlength{\locallinewidth}{\linewidth}
+\section{\module{ctypes} --- A foreign function library for Python.}
+\declaremodule{standard}{ctypes}
+\moduleauthor{Thomas Heller}{theller@python.net}
+\modulesynopsis{A foreign function library for Python.}
+\versionadded{2.5}
+
+\code{ctypes} is a foreign function library for Python.  It provides C
+compatible data types, and allows to call functions in dlls/shared
+libraries.  It can be used to wrap these libraries in pure Python.
+
+
+\subsection{ctypes tutorial\label{ctypes-ctypes-tutorial}}
+
+Note: The code samples in this tutorial uses \code{doctest} to make sure
+that they actually work.  Since some code samples behave differently
+under Linux, Windows, or Mac OS X, they contain doctest directives in
+comments.
+
+Note: Quite some code samples references the ctypes \class{c{\_}int} type.
+This type is an alias to the \class{c{\_}long} type on 32-bit systems.  So,
+you should not be confused if \class{c{\_}long} is printed if you would
+expect \class{c{\_}int} - they are actually the same type.
+
+
+\subsubsection{Loading dynamic link libraries\label{ctypes-loading-dynamic-link-libraries}}
+
+\code{ctypes} exports the \var{cdll}, and on Windows also \var{windll} and
+\var{oledll} objects to load dynamic link libraries.
+
+You load libraries by accessing them as attributes of these objects.
+\var{cdll} loads libraries which export functions using the standard
+\code{cdecl} calling convention, while \var{windll} libraries call
+functions using the \code{stdcall} calling convention. \var{oledll} also
+uses the \code{stdcall} calling convention, and assumes the functions
+return a Windows \class{HRESULT} error code. The error code is used to
+automatically raise \class{WindowsError} Python exceptions when the
+function call fails.
+
+Here are some examples for Windows, note that \code{msvcrt} is the MS
+standard C library containing most standard C functions, and uses the
+cdecl calling convention:
+\begin{verbatim}
+>>> from ctypes import *
+>>> print windll.kernel32 # doctest: +WINDOWS
+<WinDLL 'kernel32', handle ... at ...>
+>>> print cdll.msvcrt # doctest: +WINDOWS
+<CDLL 'msvcrt', handle ... at ...>
+>>> libc = cdll.msvcrt # doctest: +WINDOWS
+>>>
+\end{verbatim}
+
+Windows appends the usual '.dll' file suffix automatically.
+
+On Linux, it is required to specify the filename \emph{including} the
+extension to load a library, so attribute access does not work.
+Either the \method{LoadLibrary} method of the dll loaders should be used,
+or you should load the library by creating an instance of CDLL by
+calling the constructor:
+\begin{verbatim}
+>>> cdll.LoadLibrary("libc.so.6") # doctest: +LINUX
+<CDLL 'libc.so.6', handle ... at ...>
+>>> libc = CDLL("libc.so.6")     # doctest: +LINUX
+>>> libc                         # doctest: +LINUX
+<CDLL 'libc.so.6', handle ... at ...>
+>>>
+\end{verbatim}
+% XXX Add section for Mac OS X. 
+
+
+\subsubsection{Accessing functions from loaded dlls\label{ctypes-accessing-functions-from-loaded-dlls}}
+
+Functions are accessed as attributes of dll objects:
+\begin{verbatim}
+>>> from ctypes import *
+>>> libc.printf
+<_FuncPtr object at 0x...>
+>>> print windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
+<_FuncPtr object at 0x...>
+>>> print windll.kernel32.MyOwnFunction # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "ctypes.py", line 239, in __getattr__
+    func = _StdcallFuncPtr(name, self)
+AttributeError: function 'MyOwnFunction' not found
+>>>
+\end{verbatim}
+
+Note that win32 system dlls like \code{kernel32} and \code{user32} often
+export ANSI as well as UNICODE versions of a function. The UNICODE
+version is exported with an \code{W} appended to the name, while the ANSI
+version is exported with an \code{A} appended to the name. The win32
+\code{GetModuleHandle} function, which returns a \emph{module handle} for a
+given module name, has the following C prototype, and a macro is used
+to expose one of them as \code{GetModuleHandle} depending on whether
+UNICODE is defined or not:
+\begin{verbatim}
+/* ANSI version */
+HMODULE GetModuleHandleA(LPCSTR lpModuleName);
+/* UNICODE version */
+HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
+\end{verbatim}
+
+\var{windll} does not try to select one of them by magic, you must
+access the version you need by specifying \code{GetModuleHandleA} or
+\code{GetModuleHandleW} explicitely, and then call it with normal strings
+or unicode strings respectively.
+
+Sometimes, dlls export functions with names which aren't valid Python
+identifiers, like \code{"??2@YAPAXI@Z"}. In this case you have to use
+\code{getattr} to retrieve the function:
+\begin{verbatim}
+>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS
+<_FuncPtr object at 0x...>
+>>>
+\end{verbatim}
+
+On Windows, some dlls export functions not by name but by ordinal.
+These functions can be accessed by indexing the dll object with the
+ordinal number:
+\begin{verbatim}
+>>> cdll.kernel32[1] # doctest: +WINDOWS
+<_FuncPtr object at 0x...>
+>>> cdll.kernel32[0] # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "ctypes.py", line 310, in __getitem__
+    func = _StdcallFuncPtr(name, self)
+AttributeError: function ordinal 0 not found
+>>>
+\end{verbatim}
+
+
+\subsubsection{Calling functions\label{ctypes-calling-functions}}
+
+You can call these functions like any other Python callable. This
+example uses the \code{time()} function, which returns system time in
+seconds since the \UNIX{} epoch, and the \code{GetModuleHandleA()} function,
+which returns a win32 module handle.
+
+This example calls both functions with a NULL pointer (\code{None} should
+be used as the NULL pointer):
+\begin{verbatim}
+>>> print libc.time(None) # doctest: +SKIP
+1150640792
+>>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS
+0x1d000000
+>>>
+\end{verbatim}
+
+\code{ctypes} tries to protect you from calling functions with the wrong
+number of arguments or the wrong calling convention.  Unfortunately
+this only works on Windows.  It does this by examining the stack after
+the function returns, so although an error is raised the function
+\emph{has} been called:
+\begin{verbatim}
+>>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ValueError: Procedure probably called with not enough arguments (4 bytes missing)
+>>> windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ValueError: Procedure probably called with too many arguments (4 bytes in excess)
+>>>
+\end{verbatim}
+
+The same exception is raised when you call an \code{stdcall} function
+with the \code{cdecl} calling convention, or vice versa:
+\begin{verbatim}
+>>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ValueError: Procedure probably called with not enough arguments (4 bytes missing)
+>>>
+
+>>> windll.msvcrt.printf("spam") # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ValueError: Procedure probably called with too many arguments (4 bytes in excess)
+>>>
+\end{verbatim}
+
+To find out the correct calling convention you have to look into the C
+header file or the documentation for the function you want to call.
+
+On Windows, \code{ctypes} uses win32 structured exception handling to
+prevent crashes from general protection faults when functions are
+called with invalid argument values:
+\begin{verbatim}
+>>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+WindowsError: exception: access violation reading 0x00000020
+>>>
+\end{verbatim}
+
+There are, however, enough ways to crash Python with \code{ctypes}, so
+you should be careful anyway.
+
+\code{None}, integers, longs, byte strings and unicode strings are the
+only native Python objects that can directly be used as parameters in
+these function calls.  \code{None} is passed as a C \code{NULL} pointer,
+byte strings and unicode strings are passed as pointer to the memory
+block that contains their data (\code{char *} or \code{wchar{\_}t *}).  Python
+integers and Python longs are passed as the platforms default C
+\code{int} type, their value is masked to fit into the C type.
+
+Before we move on calling functions with other parameter types, we
+have to learn more about \code{ctypes} data types.
+
+
+\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}}
+
+\code{ctypes} defines a number of primitive C compatible data types :
+\begin{quote}
+\begin{tableiii}{l|l|l}{textrm}
+{
+ctypes type
+}
+{
+C type
+}
+{
+Python type
+}
+\lineiii{
+\class{c{\_}char}
+}
+{
+\code{char}
+}
+{
+1-character
+string
+}
+\lineiii{
+\class{c{\_}wchar}
+}
+{
+\code{wchar{\_}t}
+}
+{
+1-character
+unicode string
+}
+\lineiii{
+\class{c{\_}byte}
+}
+{
+\code{char}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}ubyte}
+}
+{
+\code{unsigned char}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}short}
+}
+{
+\code{short}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}ushort}
+}
+{
+\code{unsigned short}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}int}
+}
+{
+\code{int}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}uint}
+}
+{
+\code{unsigned int}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}long}
+}
+{
+\code{long}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}ulong}
+}
+{
+\code{unsigned long}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}longlong}
+}
+{
+\code{{\_}{\_}int64} or
+\code{long long}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}ulonglong}
+}
+{
+\code{unsigned {\_}{\_}int64} or
+\code{unsigned long long}
+}
+{
+int/long
+}
+\lineiii{
+\class{c{\_}float}
+}
+{
+\code{float}
+}
+{
+float
+}
+\lineiii{
+\class{c{\_}double}
+}
+{
+\code{double}
+}
+{
+float
+}
+\lineiii{
+\class{c{\_}char{\_}p}
+}
+{
+\code{char *}
+(NUL terminated)
+}
+{
+string or
+\code{None}
+}
+\lineiii{
+\class{c{\_}wchar{\_}p}
+}
+{
+\code{wchar{\_}t *}
+(NUL terminated)
+}
+{
+unicode or
+\code{None}
+}
+\lineiii{
+\class{c{\_}void{\_}p}
+}
+{
+\code{void *}
+}
+{
+int/long
+or \code{None}
+}
+\end{tableiii}
+\end{quote}
+
+All these types can be created by calling them with an optional
+initializer of the correct type and value:
+\begin{verbatim}
+>>> c_int()
+c_long(0)
+>>> c_char_p("Hello, World")
+c_char_p('Hello, World')
+>>> c_ushort(-3)
+c_ushort(65533)
+>>>
+\end{verbatim}
+
+Since these types are mutable, their value can also be changed
+afterwards:
+\begin{verbatim}
+>>> i = c_int(42)
+>>> print i
+c_long(42)
+>>> print i.value
+42
+>>> i.value = -99
+>>> print i.value
+-99
+>>>
+\end{verbatim}
+
+Assigning a new value to instances of the pointer types \class{c{\_}char{\_}p},
+\class{c{\_}wchar{\_}p}, and \class{c{\_}void{\_}p} changes the \emph{memory location} they
+point to, \emph{not the contents} of the memory block (of course not,
+because Python strings are immutable):
+\begin{verbatim}
+>>> s = "Hello, World"
+>>> c_s = c_char_p(s)
+>>> print c_s
+c_char_p('Hello, World')
+>>> c_s.value = "Hi, there"
+>>> print c_s
+c_char_p('Hi, there')
+>>> print s                 # first string is unchanged
+Hello, World
+>>>
+\end{verbatim}
+
+You should be careful, however, not to pass them to functions
+expecting pointers to mutable memory. If you need mutable memory
+blocks, ctypes has a \code{create{\_}string{\_}buffer} function which creates
+these in various ways.  The current memory block contents can be
+accessed (or changed) with the \code{raw} property, if you want to access
+it as NUL terminated string, use the \code{string} property:
+\begin{verbatim}
+>>> from ctypes import *
+>>> p = create_string_buffer(3)      # create a 3 byte buffer, initialized to NUL bytes
+>>> print sizeof(p), repr(p.raw)
+3 '\x00\x00\x00'
+>>> p = create_string_buffer("Hello")      # create a buffer containing a NUL terminated string
+>>> print sizeof(p), repr(p.raw)
+6 'Hello\x00'
+>>> print repr(p.value)
+'Hello'
+>>> p = create_string_buffer("Hello", 10)  # create a 10 byte buffer
+>>> print sizeof(p), repr(p.raw)
+10 'Hello\x00\x00\x00\x00\x00'
+>>> p.value = "Hi"      
+>>> print sizeof(p), repr(p.raw)
+10 'Hi\x00lo\x00\x00\x00\x00\x00'
+>>>
+\end{verbatim}
+
+The \code{create{\_}string{\_}buffer} function replaces the \code{c{\_}buffer}
+function (which is still available as an alias), as well as the
+\code{c{\_}string} function from earlier ctypes releases.  To create a
+mutable memory block containing unicode characters of the C type
+\code{wchar{\_}t} use the \code{create{\_}unicode{\_}buffer} function.
+
+
+\subsubsection{Calling functions, continued\label{ctypes-calling-functions-continued}}
+
+Note that printf prints to the real standard output channel, \emph{not} to
+\code{sys.stdout}, so these examples will only work at the console
+prompt, not from within \emph{IDLE} or \emph{PythonWin}:
+\begin{verbatim}
+>>> printf = libc.printf
+>>> printf("Hello, %s\n", "World!")
+Hello, World!
+14
+>>> printf("Hello, %S", u"World!")
+Hello, World!
+13
+>>> printf("%d bottles of beer\n", 42)
+42 bottles of beer
+19
+>>> printf("%f bottles of beer\n", 42.5)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2
+>>>
+\end{verbatim}
+
+As has been mentioned before, all Python types except integers,
+strings, and unicode strings have to be wrapped in their corresponding
+\code{ctypes} type, so that they can be converted to the required C data
+type:
+\begin{verbatim}
+>>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
+Integer 1234, double 3.1400001049
+31
+>>>
+\end{verbatim}
+
+
+\subsubsection{Calling functions with your own custom data types\label{ctypes-calling-functions-with-own-custom-data-types}}
+
+You can also customize \code{ctypes} argument conversion to allow
+instances of your own classes be used as function arguments.
+\code{ctypes} looks for an \member{{\_}as{\_}parameter{\_}} attribute and uses this as
+the function argument. Of course, it must be one of integer, string,
+or unicode:
+\begin{verbatim}
+>>> class Bottles(object):
+...     def __init__(self, number):
+...         self._as_parameter_ = number
+...
+>>> bottles = Bottles(42)
+>>> printf("%d bottles of beer\n", bottles)
+42 bottles of beer
+19
+>>>
+\end{verbatim}
+
+If you don't want to store the instance's data in the
+\member{{\_}as{\_}parameter{\_}} instance variable, you could define a \code{property}
+which makes the data avaiblable.
+
+
+\subsubsection{Specifying the required argument types (function prototypes)\label{ctypes-specifying-required-argument-types}}
+
+It is possible to specify the required argument types of functions
+exported from DLLs by setting the \member{argtypes} attribute.
+
+\member{argtypes} must be a sequence of C data types (the \code{printf}
+function is probably not a good example here, because it takes a
+variable number and different types of parameters depending on the
+format string, on the other hand this is quite handy to experiment
+with this feature):
+\begin{verbatim}
+>>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
+>>> printf("String '%s', Int %d, Double %f\n", "Hi", 10, 2.2)
+String 'Hi', Int 10, Double 2.200000
+37
+>>>
+\end{verbatim}
+
+Specifying a format protects against incompatible argument types (just
+as a prototype for a C function), and tries to convert the arguments
+to valid types:
+\begin{verbatim}
+>>> printf("%d %d %d", 1, 2, 3)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ArgumentError: argument 2: exceptions.TypeError: wrong type
+>>> printf("%s %d %f", "X", 2, 3)
+X 2 3.00000012
+12
+>>>
+\end{verbatim}
+
+If you have defined your own classes which you pass to function calls,
+you have to implement a \method{from{\_}param} class method for them to be
+able to use them in the \member{argtypes} sequence. The \method{from{\_}param}
+class method receives the Python object passed to the function call,
+it should do a typecheck or whatever is needed to make sure this
+object is acceptable, and then return the object itself, it's
+\member{{\_}as{\_}parameter{\_}} attribute, or whatever you want to pass as the C
+function argument in this case. Again, the result should be an
+integer, string, unicode, a \code{ctypes} instance, or something having
+the \member{{\_}as{\_}parameter{\_}} attribute.
+
+
+\subsubsection{Return types\label{ctypes-return-types}}
+
+By default functions are assumed to return the C \code{int} type.  Other
+return types can be specified by setting the \member{restype} attribute of
+the function object.
+
+Here is a more advanced example, it uses the \code{strchr} function, which
+expects a string pointer and a char, and returns a pointer to a
+string:
+\begin{verbatim}
+>>> strchr = libc.strchr
+>>> strchr("abcdef", ord("d")) # doctest: +SKIP
+8059983
+>>> strchr.restype = c_char_p # c_char_p is a pointer to a string
+>>> strchr("abcdef", ord("d"))
+'def'
+>>> print strchr("abcdef", ord("x"))
+None
+>>>
+\end{verbatim}
+
+If you want to avoid the \code{ord("x")} calls above, you can set the
+\member{argtypes} attribute, and the second argument will be converted from
+a single character Python string into a C char:
+\begin{verbatim}
+>>> strchr.restype = c_char_p
+>>> strchr.argtypes = [c_char_p, c_char]
+>>> strchr("abcdef", "d")
+'def'
+>>> strchr("abcdef", "def")
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ArgumentError: argument 2: exceptions.TypeError: one character string expected
+>>> print strchr("abcdef", "x")
+None
+>>> strchr("abcdef", "d")
+'def'
+>>>
+\end{verbatim}
+
+You can also use a callable Python object (a function or a class for
+example) as the \member{restype} attribute, if the foreign function returns
+an integer.  The callable will be called with the \code{integer} the C
+function returns, and the result of this call will be used as the
+result of your function call. This is useful to check for error return
+values and automatically raise an exception:
+\begin{verbatim}
+>>> GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
+>>> def ValidHandle(value):
+...     if value == 0:
+...         raise WinError()
+...     return value
+...
+>>>
+>>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS
+>>> GetModuleHandle(None) # doctest: +WINDOWS
+486539264
+>>> GetModuleHandle("something silly") # doctest: +WINDOWS
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "<stdin>", line 3, in ValidHandle
+WindowsError: [Errno 126] The specified module could not be found.
+>>>
+\end{verbatim}
+
+\code{WinError} is a function which will call Windows \code{FormatMessage()}
+api to get the string representation of an error code, and \emph{returns}
+an exception.  \code{WinError} takes an optional error code parameter, if
+no one is used, it calls \function{GetLastError()} to retrieve it.
+
+Please note that a much more powerful error checking mechanism is
+available through the \member{errcheck} attribute; see the reference manual
+for details.
+
+
+\subsubsection{Passing pointers (or: passing parameters by reference)\label{ctypes-passing-pointers}}
+
+Sometimes a C api function expects a \emph{pointer} to a data type as
+parameter, probably to write into the corresponding location, or if
+the data is too large to be passed by value. This is also known as
+\emph{passing parameters by reference}.
+
+\code{ctypes} exports the \function{byref} function which is used to pass
+parameters by reference.  The same effect can be achieved with the
+\code{pointer} function, although \code{pointer} does a lot more work since
+it constructs a real pointer object, so it is faster to use \function{byref}
+if you don't need the pointer object in Python itself:
+\begin{verbatim}
+>>> i = c_int()
+>>> f = c_float()
+>>> s = create_string_buffer('\000' * 32)
+>>> print i.value, f.value, repr(s.value)
+0 0.0 ''
+>>> libc.sscanf("1 3.14 Hello", "%d %f %s",
+...             byref(i), byref(f), s)
+3
+>>> print i.value, f.value, repr(s.value)
+1 3.1400001049 'Hello'
+>>>
+\end{verbatim}
+
+
+\subsubsection{Structures and unions\label{ctypes-structures-unions}}
+
+Structures and unions must derive from the \class{Structure} and \class{Union}
+base classes which are defined in the \code{ctypes} module. Each subclass
+must define a \member{{\_}fields{\_}} attribute.  \member{{\_}fields{\_}} must be a list of
+\emph{2-tuples}, containing a \emph{field name} and a \emph{field type}.
+
+The field type must be a \code{ctypes} type like \class{c{\_}int}, or any other
+derived \code{ctypes} type: structure, union, array, pointer.
+
+Here is a simple example of a POINT structure, which contains two
+integers named \code{x} and \code{y}, and also shows how to initialize a
+structure in the constructor:
+\begin{verbatim}
+>>> from ctypes import *
+>>> class POINT(Structure):
+...     _fields_ = [("x", c_int),
+...                 ("y", c_int)]
+...
+>>> point = POINT(10, 20)
+>>> print point.x, point.y
+10 20
+>>> point = POINT(y=5)
+>>> print point.x, point.y
+0 5
+>>> POINT(1, 2, 3)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ValueError: too many initializers
+>>>
+\end{verbatim}
+
+You can, however, build much more complicated structures. Structures
+can itself contain other structures by using a structure as a field
+type.
+
+Here is a RECT structure which contains two POINTs named \code{upperleft}
+and \code{lowerright}
+\begin{verbatim}
+>>> class RECT(Structure):
+...     _fields_ = [("upperleft", POINT),
+...                 ("lowerright", POINT)]
+...
+>>> rc = RECT(point)
+>>> print rc.upperleft.x, rc.upperleft.y
+0 5
+>>> print rc.lowerright.x, rc.lowerright.y
+0 0
+>>>
+\end{verbatim}
+
+Nested structures can also be initialized in the constructor in
+several ways:
+\begin{verbatim}
+>>> r = RECT(POINT(1, 2), POINT(3, 4))
+>>> r = RECT((1, 2), (3, 4))
+\end{verbatim}
+
+Fields descriptors can be retrieved from the \emph{class}, they are useful
+for debugging because they can provide useful information:
+\begin{verbatim}
+>>> print POINT.x
+<Field type=c_long, ofs=0, size=4>
+>>> print POINT.y
+<Field type=c_long, ofs=4, size=4>
+>>>
+\end{verbatim}
+
+
+\subsubsection{Structure/union alignment and byte order\label{ctypes-structureunion-alignment-byte-order}}
+
+By default, Structure and Union fields are aligned in the same way the
+C compiler does it. It is possible to override this behaviour be
+specifying a \member{{\_}pack{\_}} class attribute in the subclass
+definition. This must be set to a positive integer and specifies the
+maximum alignment for the fields. This is what \code{{\#}pragma pack(n)}
+also does in MSVC.
+
+\code{ctypes} uses the native byte order for Structures and Unions.  To
+build structures with non-native byte order, you can use one of the
+BigEndianStructure, LittleEndianStructure, BigEndianUnion, and
+LittleEndianUnion base classes.  These classes cannot contain pointer
+fields.
+
+
+\subsubsection{Bit fields in structures and unions\label{ctypes-bit-fields-in-structures-unions}}
+
+It is possible to create structures and unions containing bit fields.
+Bit fields are only possible for integer fields, the bit width is
+specified as the third item in the \member{{\_}fields{\_}} tuples:
+\begin{verbatim}
+>>> class Int(Structure):
+...     _fields_ = [("first_16", c_int, 16),
+...                 ("second_16", c_int, 16)]
+...
+>>> print Int.first_16
+<Field type=c_long, ofs=0:0, bits=16>
+>>> print Int.second_16
+<Field type=c_long, ofs=0:16, bits=16>
+>>>
+\end{verbatim}
+
+
+\subsubsection{Arrays\label{ctypes-arrays}}
+
+Arrays are sequences, containing a fixed number of instances of the
+same type.
+
+The recommended way to create array types is by multiplying a data
+type with a positive integer:
+\begin{verbatim}
+TenPointsArrayType = POINT * 10
+\end{verbatim}
+
+Here is an example of an somewhat artifical data type, a structure
+containing 4 POINTs among other stuff:
+\begin{verbatim}
+>>> from ctypes import *
+>>> class POINT(Structure):
+...    _fields_ = ("x", c_int), ("y", c_int)
+...
+>>> class MyStruct(Structure):
+...    _fields_ = [("a", c_int),
+...                ("b", c_float),
+...                ("point_array", POINT * 4)]
+>>>
+>>> print len(MyStruct().point_array)
+4
+>>>
+\end{verbatim}
+
+Instances are created in the usual way, by calling the class:
+\begin{verbatim}
+arr = TenPointsArrayType()
+for pt in arr:
+    print pt.x, pt.y
+\end{verbatim}
+
+The above code print a series of \code{0 0} lines, because the array
+contents is initialized to zeros.
+
+Initializers of the correct type can also be specified:
+\begin{verbatim}
+>>> from ctypes import *
+>>> TenIntegers = c_int * 10
+>>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+>>> print ii
+<c_long_Array_10 object at 0x...>
+>>> for i in ii: print i,
+...
+1 2 3 4 5 6 7 8 9 10
+>>>
+\end{verbatim}
+
+
+\subsubsection{Pointers\label{ctypes-pointers}}
+
+Pointer instances are created by calling the \code{pointer} function on a
+\code{ctypes} type:
+\begin{verbatim}
+>>> from ctypes import *
+>>> i = c_int(42)
+>>> pi = pointer(i)
+>>>
+\end{verbatim}
+
+Pointer instances have a \code{contents} attribute which returns the
+object to which the pointer points, the \code{i} object above:
+\begin{verbatim}
+>>> pi.contents
+c_long(42)
+>>>
+\end{verbatim}
+
+Note that \code{ctypes} does not have OOR (original object return), it
+constructs a new, equivalent object each time you retrieve an
+attribute:
+\begin{verbatim}
+>>> pi.contents is i
+False
+>>> pi.contents is pi.contents
+False
+>>>
+\end{verbatim}
+
+Assigning another \class{c{\_}int} instance to the pointer's contents
+attribute would cause the pointer to point to the memory location
+where this is stored:
+\begin{verbatim}
+>>> i = c_int(99)
+>>> pi.contents = i
+>>> pi.contents
+c_long(99)
+>>>
+\end{verbatim}
+
+Pointer instances can also be indexed with integers:
+\begin{verbatim}
+>>> pi[0]
+99
+>>>
+\end{verbatim}
+
+Assigning to an integer index changes the pointed to value:
+\begin{verbatim}
+>>> print i
+c_long(99)
+>>> pi[0] = 22
+>>> print i
+c_long(22)
+>>>
+\end{verbatim}
+
+It is also possible to use indexes different from 0, but you must know
+what you're doing, just as in C: You can access or change arbitrary
+memory locations. Generally you only use this feature if you receive a
+pointer from a C function, and you \emph{know} that the pointer actually
+points to an array instead of a single item.
+
+Behind the scenes, the \code{pointer} function does more than simply
+create pointer instances, it has to create pointer \emph{types} first.
+This is done with the \code{POINTER} function, which accepts any
+\code{ctypes} type, and returns a new type:
+\begin{verbatim}
+>>> PI = POINTER(c_int)
+>>> PI
+<class 'ctypes.LP_c_long'>
+>>> PI(42)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: expected c_long instead of int
+>>> PI(c_int(42))
+<ctypes.LP_c_long object at 0x...>
+>>>
+\end{verbatim}
+
+Calling the pointer type without an argument creates a \code{NULL}
+pointer.  \code{NULL} pointers have a \code{False} boolean value:
+\begin{verbatim}
+>>> null_ptr = POINTER(c_int)()
+>>> print bool(null_ptr)
+False
+>>>
+\end{verbatim}
+
+\code{ctypes} checks for \code{NULL} when dereferencing pointers (but
+dereferencing non-\code{NULL} pointers would crash Python):
+\begin{verbatim}
+>>> null_ptr[0]
+Traceback (most recent call last):
+    ....
+ValueError: NULL pointer access
+>>>
+
+>>> null_ptr[0] = 1234
+Traceback (most recent call last):
+    ....
+ValueError: NULL pointer access
+>>>
+\end{verbatim}
+
+
+\subsubsection{Type conversions\label{ctypes-type-conversions}}
+
+Usually, ctypes does strict type checking.  This means, if you have
+\code{POINTER(c{\_}int)} in the \member{argtypes} list of a function or as the
+type of a member field in a structure definition, only instances of
+exactly the same type are accepted.  There are some exceptions to this
+rule, where ctypes accepts other objects.  For example, you can pass
+compatible array instances instead of pointer types.  So, for
+\code{POINTER(c{\_}int)}, ctypes accepts an array of c{\_}int:
+\begin{verbatim}
+>>> class Bar(Structure):
+...     _fields_ = [("count", c_int), ("values", POINTER(c_int))]
+...
+>>> bar = Bar()
+>>> bar.values = (c_int * 3)(1, 2, 3)
+>>> bar.count = 3
+>>> for i in range(bar.count):
+...     print bar.values[i]
+...
+1
+2
+3
+>>>
+\end{verbatim}
+
+To set a POINTER type field to \code{NULL}, you can assign \code{None}:
+\begin{verbatim}
+>>> bar.values = None
+>>>
+\end{verbatim}
+
+XXX list other conversions...
+
+Sometimes you have instances of incompatible types.  In \code{C}, you can
+cast one type into another type.  \code{ctypes} provides a \code{cast}
+function which can be used in the same way.  The \code{Bar} structure
+defined above accepts \code{POINTER(c{\_}int)} pointers or \class{c{\_}int} arrays
+for its \code{values} field, but not instances of other types:
+\begin{verbatim}
+>>> bar.values = (c_byte * 4)()
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
+>>>
+\end{verbatim}
+
+For these cases, the \code{cast} function is handy.
+
+The \code{cast} function can be used to cast a ctypes instance into a
+pointer to a different ctypes data type.  \code{cast} takes two
+parameters, a ctypes object that is or can be converted to a pointer
+of some kind, and a ctypes pointer type.  It returns an instance of
+the second argument, which references the same memory block as the
+first argument:
+\begin{verbatim}
+>>> a = (c_byte * 4)()
+>>> cast(a, POINTER(c_int))
+<ctypes.LP_c_long object at ...>
+>>>
+\end{verbatim}
+
+So, \code{cast} can be used to assign to the \code{values} field of \code{Bar}
+the structure:
+\begin{verbatim}
+>>> bar = Bar()
+>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
+>>> print bar.values[0]
+0
+>>>
+\end{verbatim}
+
+
+\subsubsection{Incomplete Types\label{ctypes-incomplete-types}}
+
+\emph{Incomplete Types} are structures, unions or arrays whose members are
+not yet specified. In C, they are specified by forward declarations, which
+are defined later:
+\begin{verbatim}
+struct cell; /* forward declaration */
+
+struct {
+    char *name;
+    struct cell *next;
+} cell;
+\end{verbatim}
+
+The straightforward translation into ctypes code would be this, but it
+does not work:
+\begin{verbatim}
+>>> class cell(Structure):
+...     _fields_ = [("name", c_char_p),
+...                 ("next", POINTER(cell))]
+...
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "<stdin>", line 2, in cell
+NameError: name 'cell' is not defined
+>>>
+\end{verbatim}
+
+because the new \code{class cell} is not available in the class statement
+itself.  In \code{ctypes}, we can define the \code{cell} class and set the
+\member{{\_}fields{\_}} attribute later, after the class statement:
+\begin{verbatim}
+>>> from ctypes import *
+>>> class cell(Structure):
+...     pass
+...
+>>> cell._fields_ = [("name", c_char_p),
+...                  ("next", POINTER(cell))]
+>>>
+\end{verbatim}
+
+Lets try it. We create two instances of \code{cell}, and let them point
+to each other, and finally follow the pointer chain a few times:
+\begin{verbatim}
+>>> c1 = cell()
+>>> c1.name = "foo"
+>>> c2 = cell()
+>>> c2.name = "bar"
+>>> c1.next = pointer(c2)
+>>> c2.next = pointer(c1)
+>>> p = c1
+>>> for i in range(8):
+...     print p.name,
+...     p = p.next[0]
+...
+foo bar foo bar foo bar foo bar
+>>>    
+\end{verbatim}
+
+
+\subsubsection{Callback functions\label{ctypes-callback-functions}}
+
+\code{ctypes} allows to create C callable function pointers from Python
+callables. These are sometimes called \emph{callback functions}.
+
+First, you must create a class for the callback function, the class
+knows the calling convention, the return type, and the number and
+types of arguments this function will receive.
+
+The CFUNCTYPE factory function creates types for callback functions
+using the normal cdecl calling convention, and, on Windows, the
+WINFUNCTYPE factory function creates types for callback functions
+using the stdcall calling convention.
+
+Both of these factory functions are called with the result type as
+first argument, and the callback functions expected argument types as
+the remaining arguments.
+
+I will present an example here which uses the standard C library's
+\function{qsort} function, this is used to sort items with the help of a
+callback function. \function{qsort} will be used to sort an array of
+integers:
+\begin{verbatim}
+>>> IntArray5 = c_int * 5
+>>> ia = IntArray5(5, 1, 7, 33, 99)
+>>> qsort = libc.qsort
+>>> qsort.restype = None
+>>>
+\end{verbatim}
+
+\function{qsort} must be called with a pointer to the data to sort, the
+number of items in the data array, the size of one item, and a pointer
+to the comparison function, the callback. The callback will then be
+called with two pointers to items, and it must return a negative
+integer if the first item is smaller than the second, a zero if they
+are equal, and a positive integer else.
+
+So our callback function receives pointers to integers, and must
+return an integer. First we create the \code{type} for the callback
+function:
+\begin{verbatim}
+>>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
+>>>
+\end{verbatim}
+
+For the first implementation of the callback function, we simply print
+the arguments we get, and return 0 (incremental development ;-):
+\begin{verbatim}
+>>> def py_cmp_func(a, b):
+...     print "py_cmp_func", a, b
+...     return 0
+...
+>>>
+\end{verbatim}
+
+Create the C callable callback:
+\begin{verbatim}
+>>> cmp_func = CMPFUNC(py_cmp_func)
+>>>
+\end{verbatim}
+
+And we're ready to go:
+\begin{verbatim}
+>>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+>>>
+\end{verbatim}
+
+We know how to access the contents of a pointer, so lets redefine our callback:
+\begin{verbatim}
+>>> def py_cmp_func(a, b):
+...     print "py_cmp_func", a[0], b[0]
+...     return 0
+...
+>>> cmp_func = CMPFUNC(py_cmp_func)
+>>>
+\end{verbatim}
+
+Here is what we get on Windows:
+\begin{verbatim}
+>>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
+py_cmp_func 7 1
+py_cmp_func 33 1
+py_cmp_func 99 1
+py_cmp_func 5 1
+py_cmp_func 7 5
+py_cmp_func 33 5
+py_cmp_func 99 5
+py_cmp_func 7 99
+py_cmp_func 33 99
+py_cmp_func 7 33
+>>>
+\end{verbatim}
+
+It is funny to see that on linux the sort function seems to work much
+more efficient, it is doing less comparisons:
+\begin{verbatim}
+>>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +LINUX
+py_cmp_func 5 1
+py_cmp_func 33 99
+py_cmp_func 7 33
+py_cmp_func 5 7
+py_cmp_func 1 7
+>>>
+\end{verbatim}
+
+Ah, we're nearly done! The last step is to actually compare the two
+items and return a useful result:
+\begin{verbatim}
+>>> def py_cmp_func(a, b):
+...     print "py_cmp_func", a[0], b[0]
+...     return a[0] - b[0]
+...
+>>>
+\end{verbatim}
+
+Final run on Windows:
+\begin{verbatim}
+>>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +WINDOWS
+py_cmp_func 33 7
+py_cmp_func 99 33
+py_cmp_func 5 99
+py_cmp_func 1 99
+py_cmp_func 33 7
+py_cmp_func 1 33
+py_cmp_func 5 33
+py_cmp_func 5 7
+py_cmp_func 1 7
+py_cmp_func 5 1
+>>>
+\end{verbatim}
+
+and on Linux:
+\begin{verbatim}
+>>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +LINUX
+py_cmp_func 5 1
+py_cmp_func 33 99
+py_cmp_func 7 33
+py_cmp_func 1 7
+py_cmp_func 5 7
+>>>
+\end{verbatim}
+
+It is quite interesting to see that the Windows \function{qsort} function
+needs more comparisons than the linux version!
+
+As we can easily check, our array sorted now:
+\begin{verbatim}
+>>> for i in ia: print i,
+...
+1 5 7 33 99
+>>>
+\end{verbatim}
+
+\textbf{Important note for callback functions:}
+
+Make sure you keep references to CFUNCTYPE objects as long as they are
+used from C code. \code{ctypes} doesn't, and if you don't, they may be
+garbage collected, crashing your program when a callback is made.
+
+
+\subsubsection{Accessing values exported from dlls\label{ctypes-accessing-values-exported-from-dlls}}
+
+Sometimes, a dll not only exports functions, it also exports
+variables. An example in the Python library itself is the
+\code{Py{\_}OptimizeFlag}, an integer set to 0, 1, or 2, depending on the
+\programopt{-O} or \programopt{-OO} flag given on startup.
+
+\code{ctypes} can access values like this with the \method{in{\_}dll} class
+methods of the type.  \var{pythonapi} ìs a predefined symbol giving
+access to the Python C api:
+\begin{verbatim}
+>>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
+>>> print opt_flag
+c_long(0)
+>>>
+\end{verbatim}
+
+If the interpreter would have been started with \programopt{-O}, the sample
+would have printed \code{c{\_}long(1)}, or \code{c{\_}long(2)} if \programopt{-OO} would have
+been specified.
+
+An extended example which also demonstrates the use of pointers
+accesses the \code{PyImport{\_}FrozenModules} pointer exported by Python.
+
+Quoting the Python docs: \emph{This pointer is initialized to point to an
+array of ``struct {\_}frozen`` records, terminated by one whose members
+are all NULL or zero. When a frozen module is imported, it is searched
+in this table. Third-party code could play tricks with this to provide
+a dynamically created collection of frozen modules.}
+
+So manipulating this pointer could even prove useful. To restrict the
+example size, we show only how this table can be read with
+\code{ctypes}:
+\begin{verbatim}
+>>> from ctypes import *
+>>>
+>>> class struct_frozen(Structure):
+...     _fields_ = [("name", c_char_p),
+...                 ("code", POINTER(c_ubyte)),
+...                 ("size", c_int)]
+...
+>>>
+\end{verbatim}
+
+We have defined the \code{struct {\_}frozen} data type, so we can get the
+pointer to the table:
+\begin{verbatim}
+>>> FrozenTable = POINTER(struct_frozen)
+>>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
+>>>
+\end{verbatim}
+
+Since \code{table} is a \code{pointer} to the array of \code{struct{\_}frozen}
+records, we can iterate over it, but we just have to make sure that
+our loop terminates, because pointers have no size. Sooner or later it
+would probably crash with an access violation or whatever, so it's
+better to break out of the loop when we hit the NULL entry:
+\begin{verbatim}
+>>> for item in table:
+...    print item.name, item.size
+...    if item.name is None:
+...        break
+...
+__hello__ 104
+__phello__ -104
+__phello__.spam 104
+None 0
+>>>
+\end{verbatim}
+
+The fact that standard Python has a frozen module and a frozen package
+(indicated by the negative size member) is not wellknown, it is only
+used for testing. Try it out with \code{import {\_}{\_}hello{\_}{\_}} for example.
+
+
+\subsubsection{Surprises\label{ctypes-surprises}}
+
+There are some edges in \code{ctypes} where you may be expect something
+else than what actually happens.
+
+Consider the following example:
+\begin{verbatim}
+>>> from ctypes import *
+>>> class POINT(Structure):
+...     _fields_ = ("x", c_int), ("y", c_int)
+...
+>>> class RECT(Structure):
+...     _fields_ = ("a", POINT), ("b", POINT)
+...
+>>> p1 = POINT(1, 2)
+>>> p2 = POINT(3, 4)
+>>> rc = RECT(p1, p2)
+>>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
+1 2 3 4
+>>> # now swap the two points
+>>> rc.a, rc.b = rc.b, rc.a
+>>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
+3 4 3 4
+>>>
+\end{verbatim}
+
+Hm. We certainly expected the last statement to print \code{3 4 1 2}.
+What happended? Here are the steps of the \code{rc.a, rc.b = rc.b, rc.a}
+line above:
+\begin{verbatim}
+>>> temp0, temp1 = rc.b, rc.a
+>>> rc.a = temp0
+>>> rc.b = temp1
+>>>
+\end{verbatim}
+
+Note that \code{temp0} and \code{temp1} are objects still using the internal
+buffer of the \code{rc} object above. So executing \code{rc.a = temp0}
+copies the buffer contents of \code{temp0} into \code{rc} 's buffer.  This,
+in turn, changes the contents of \code{temp1}. So, the last assignment
+\code{rc.b = temp1}, doesn't have the expected effect.
+
+Keep in mind that retrieving subobjects from Structure, Unions, and
+Arrays doesn't \emph{copy} the subobject, instead it retrieves a wrapper
+object accessing the root-object's underlying buffer.
+
+Another example that may behave different from what one would expect is this:
+\begin{verbatim}
+>>> s = c_char_p()
+>>> s.value = "abc def ghi"
+>>> s.value
+'abc def ghi'
+>>> s.value is s.value
+False
+>>>
+\end{verbatim}
+
+Why is it printing \code{False}?  ctypes instances are objects containing
+a memory block plus some descriptors accessing the contents of the
+memory.  Storing a Python object in the memory block does not store
+the object itself, instead the \code{contents} of the object is stored.
+Accessing the contents again constructs a new Python each time!
+
+
+\subsubsection{Variable-sized data types\label{ctypes-variable-sized-data-types}}
+
+\code{ctypes} provides some support for variable-sized arrays and
+structures (this was added in version 0.9.9.7).
+
+The \code{resize} function can be used to resize the memory buffer of an
+existing ctypes object.  The function takes the object as first
+argument, and the requested size in bytes as the second argument.  The
+memory block cannot be made smaller than the natural memory block
+specified by the objects type, a \code{ValueError} is raised if this is
+tried:
+\begin{verbatim}
+>>> short_array = (c_short * 4)()
+>>> print sizeof(short_array)
+8
+>>> resize(short_array, 4)
+Traceback (most recent call last):
+    ...
+ValueError: minimum size is 8
+>>> resize(short_array, 32)
+>>> sizeof(short_array)
+32
+>>> sizeof(type(short_array))
+8
+>>>
+\end{verbatim}
+
+This is nice and fine, but how would one access the additional
+elements contained in this array?  Since the type still only knows
+about 4 elements, we get errors accessing other elements:
+\begin{verbatim}
+>>> short_array[:]
+[0, 0, 0, 0]
+>>> short_array[7]
+Traceback (most recent call last):
+    ...
+IndexError: invalid index
+>>>
+\end{verbatim}
+
+Another way to use variable-sized data types with \code{ctypes} is to use
+the dynamic nature of Python, and (re-)define the data type after the
+required size is already known, on a case by case basis.
+
+
+\subsubsection{Bugs, ToDo and non-implemented things\label{ctypes-bugs-todo-non-implemented-things}}
+
+Enumeration types are not implemented. You can do it easily yourself,
+using \class{c{\_}int} as the base class.
+
+\code{long double} is not implemented.
+% Local Variables:
+% compile-command: "make.bat"
+% End: 
+
+
+\subsection{ctypes reference\label{ctypes-ctypes-reference}}
+
+
+\subsubsection{Finding shared libraries\label{ctypes-finding-shared-libraries}}
+
+When programming in a compiled language, shared libraries are accessed
+when compiling/linking a program, and when the program is run.
+
+The purpose of the \code{find{\_}library} function is to locate a library in
+a way similar to what the compiler does (on platforms with several
+versions of a shared library the most recent should be loaded), while
+the ctypes library loaders act like when a program is run, and call
+the runtime loader directly.
+
+The \code{ctypes.util} module provides a function which can help to
+determine the library to load.
+
+\begin{datadescni}{find_library(name)}
+Try to find a library and return a pathname.  \var{name} is the
+library name without any prefix like \var{lib}, suffix like \code{.so},
+\code{.dylib} or version number (this is the form used for the posix
+linker option \programopt{-l}).  If no library can be found, returns
+\code{None}.
+\end{datadescni}
+
+The exact functionality is system dependend.
+
+On Linux, \code{find{\_}library} tries to run external programs
+(/sbin/ldconfig, gcc, and objdump) to find the library file.  It
+returns the filename of the library file.  Here are sone examples:
+\begin{verbatim}
+>>> from ctypes.util import find_library
+>>> find_library("m")
+'libm.so.6'
+>>> find_library("c")
+'libc.so.6'
+>>> find_library("bz2")
+'libbz2.so.1.0'
+>>>
+\end{verbatim}
+
+On OS X, \code{find{\_}library} tries several predefined naming schemes and
+paths to locate the library, and returns a full pathname if successfull:
+\begin{verbatim}
+>>> from ctypes.util import find_library
+>>> find_library("c")
+'/usr/lib/libc.dylib'
+>>> find_library("m")
+'/usr/lib/libm.dylib'
+>>> find_library("bz2")
+'/usr/lib/libbz2.dylib'
+>>> find_library("AGL")
+'/System/Library/Frameworks/AGL.framework/AGL'
+>>>
+\end{verbatim}
+
+On Windows, \code{find{\_}library} searches along the system search path,
+and returns the full pathname, but since there is no predefined naming
+scheme a call like \code{find{\_}library("c")} will fail and return
+\code{None}.
+
+If wrapping a shared library with \code{ctypes}, it \emph{may} be better to
+determine the shared library name at development type, and hardcode
+that into the wrapper module instead of using \code{find{\_}library} to
+locate the library at runtime.
+
+
+\subsubsection{Loading shared libraries\label{ctypes-loading-shared-libraries}}
+
+There are several ways to loaded shared libraries into the Python
+process.  One way is to instantiate one of the following classes:
+
+\begin{classdesc}{CDLL}{name, mode=DEFAULT_MODE, handle=None}
+Instances of this class represent loaded shared libraries.
+Functions in these libraries use the standard C calling
+convention, and are assumed to return \code{int}.
+\end{classdesc}
+
+\begin{classdesc}{OleDLL}{name, mode=DEFAULT_MODE, handle=None}
+Windows only: Instances of this class represent loaded shared
+libraries, functions in these libraries use the \code{stdcall}
+calling convention, and are assumed to return the windows specific
+\class{HRESULT} code.  \class{HRESULT} values contain information
+specifying whether the function call failed or succeeded, together
+with additional error code.  If the return value signals a
+failure, an \class{WindowsError} is automatically raised.
+\end{classdesc}
+
+\begin{classdesc}{WinDLL}{name, mode=DEFAULT_MODE, handle=None}
+Windows only: Instances of this class represent loaded shared
+libraries, functions in these libraries use the \code{stdcall}
+calling convention, and are assumed to return \code{int} by default.
+
+On Windows CE only the standard calling convention is used, for
+convenience the \class{WinDLL} and \class{OleDLL} use the standard calling
+convention on this platform.
+\end{classdesc}
+
+The Python GIL is released before calling any function exported by
+these libraries, and reaquired afterwards.
+
+\begin{classdesc}{PyDLL}{name, mode=DEFAULT_MODE, handle=None}
+Instances of this class behave like \class{CDLL} instances, except
+that the Python GIL is \emph{not} released during the function call,
+and after the function execution the Python error flag is checked.
+If the error flag is set, a Python exception is raised.
+
+Thus, this is only useful to call Python C api functions directly.
+\end{classdesc}
+
+All these classes can be instantiated by calling them with at least
+one argument, the pathname of the shared library.  If you have an
+existing handle to an already loaded shard library, it can be passed
+as the \code{handle} named parameter, otherwise the underlying platforms
+\code{dlopen} or \method{LoadLibrary} function is used to load the library
+into the process, and to get a handle to it.
+
+The \var{mode} parameter can be used to specify how the library is
+loaded.  For details, consult the \code{dlopen(3)} manpage, on Windows,
+\var{mode} is ignored.
+
+\begin{datadescni}{RTLD_GLOBAL}
+Flag to use as \var{mode} parameter.  On platforms where this flag
+is not available, it is defined as the integer zero.
+\end{datadescni}
+
+\begin{datadescni}{RTLD_LOCAL}
+Flag to use as \var{mode} parameter.  On platforms where this is not
+available, it is the same as \var{RTLD{\_}GLOBAL}.
+\end{datadescni}
+
+\begin{datadescni}{DEFAULT_MODE}
+The default mode which is used to load shared libraries.  On OSX
+10.3, this is \var{RTLD{\_}GLOBAL}, otherwise it is the same as
+\var{RTLD{\_}LOCAL}.
+\end{datadescni}
+
+Instances of these classes have no public methods, however
+\method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} have special behaviour: functions
+exported by the shared library can be accessed as attributes of by
+index.  Please note that both \method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}}
+cache their result, so calling them repeatedly returns the same object
+each time.
+
+The following public attributes are available, their name starts with
+an underscore to not clash with exported function names:
+
+\begin{memberdesc}{_handle}
+The system handle used to access the library.
+\end{memberdesc}
+
+\begin{memberdesc}{_name}
+The name of the library passed in the contructor.
+\end{memberdesc}
+
+Shared libraries can also be loaded by using one of the prefabricated
+objects, which are instances of the \class{LibraryLoader} class, either by
+calling the \method{LoadLibrary} method, or by retrieving the library as
+attribute of the loader instance.
+
+\begin{classdesc}{LibraryLoader}{dlltype}
+Class which loads shared libraries.  \code{dlltype} should be one
+of the \class{CDLL}, \class{PyDLL}, \class{WinDLL}, or \class{OleDLL} types.
+
+\method{{\_}{\_}getattr{\_}{\_}} has special behaviour: It allows to load a shared
+library by accessing it as attribute of a library loader
+instance.  The result is cached, so repeated attribute accesses
+return the same library each time.
+\end{classdesc}
+
+\begin{methoddesc}{LoadLibrary}{name}
+Load a shared library into the process and return it.  This method
+always returns a new instance of the library.
+\end{methoddesc}
+
+These prefabricated library loaders are available:
+
+\begin{datadescni}{cdll}
+Creates \class{CDLL} instances.
+\end{datadescni}
+
+\begin{datadescni}{windll}
+Windows only: Creates \class{WinDLL} instances.
+\end{datadescni}
+
+\begin{datadescni}{oledll}
+Windows only: Creates \class{OleDLL} instances.
+\end{datadescni}
+
+\begin{datadescni}{pydll}
+Creates \class{PyDLL} instances.
+\end{datadescni}
+
+For accessing the C Python api directly, a ready-to-use Python shared
+library object is available:
+
+\begin{datadescni}{pythonapi}
+An instance of \class{PyDLL} that exposes Python C api functions as
+attributes.  Note that all these functions are assumed to return C
+\code{int}, which is of course not always the truth, so you have to
+assign the correct \member{restype} attribute to use these functions.
+\end{datadescni}
+
+
+\subsubsection{Foreign functions\label{ctypes-foreign-functions}}
+
+As explained in the previous section, foreign functions can be
+accessed as attributes of loaded shared libraries.  The function
+objects created in this way by default accept any number of arguments,
+accept any ctypes data instances as arguments, and return the default
+result type specified by the library loader.  They are instances of a
+private class:
+
+\begin{classdesc*}{_FuncPtr}
+Base class for C callable foreign functions.
+\end{classdesc*}
+
+Instances of foreign functions are also C compatible data types; they
+represent C function pointers.
+
+This behaviour can be customized by assigning to special attributes of
+the foreign function object.
+
+\begin{memberdesc}{restype}
+Assign a ctypes type to specify the result type of the foreign
+function.  Use \code{None} for \code{void} a function not returning
+anything.
+
+It is possible to assign a callable Python object that is not a
+ctypes type, in this case the function is assumed to return a
+C \code{int}, and the callable will be called with this integer,
+allowing to do further processing or error checking.  Using this
+is deprecated, for more flexible postprocessing or error checking
+use a ctypes data type as \member{restype} and assign a callable to the
+\member{errcheck} attribute.
+\end{memberdesc}
+
+\begin{memberdesc}{argtypes}
+Assign a tuple of ctypes types to specify the argument types that
+the function accepts.  Functions using the \code{stdcall} calling
+convention can only be called with the same number of arguments as
+the length of this tuple; functions using the C calling convention
+accept additional, unspecified arguments as well.
+
+When a foreign function is called, each actual argument is passed
+to the \method{from{\_}param} class method of the items in the
+\member{argtypes} tuple, this method allows to adapt the actual
+argument to an object that the foreign function accepts.  For
+example, a \class{c{\_}char{\_}p} item in the \member{argtypes} tuple will
+convert a unicode string passed as argument into an byte string
+using ctypes conversion rules.
+
+New: It is now possible to put items in argtypes which are not
+ctypes types, but each item must have a \method{from{\_}param} method
+which returns a value usable as argument (integer, string, ctypes
+instance).  This allows to define adapters that can adapt custom
+objects as function parameters.
+\end{memberdesc}
+
+\begin{memberdesc}{errcheck}
+Assign a Python function or another callable to this attribute.
+The callable will be called with three or more arguments:
+\end{memberdesc}
+
+\begin{funcdescni}{callable}{result, func, arguments}
+\code{result} is what the foreign function returns, as specified by the
+\member{restype} attribute.
+
+\code{func} is the foreign function object itself, this allows to
+reuse the same callable object to check or postprocess the results
+of several functions.
+
+\code{arguments} is a tuple containing the parameters originally
+passed to the function call, this allows to specialize the
+behaviour on the arguments used.
+
+The object that this function returns will be returned from the
+foreign function call, but it can also check the result value and
+raise an exception if the foreign function call failed.
+\end{funcdescni}
+
+\begin{excdesc}{ArgumentError()}
+This exception is raised when a foreign function call cannot
+convert one of the passed arguments.
+\end{excdesc}
+
+
+\subsubsection{Function prototypes\label{ctypes-function-prototypes}}
+
+Foreign functions can also be created by instantiating function
+prototypes.  Function prototypes are similar to function prototypes in
+C; they describe a function (return type, argument types, calling
+convention) without defining an implementation.  The factory
+functions must be called with the desired result type and the argument
+types of the function.
+
+\begin{funcdesc}{CFUNCTYPE}{restype, *argtypes}
+The returned function prototype creates functions that use the
+standard C calling convention.  The function will release the GIL
+during the call.
+\end{funcdesc}
+
+\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes}
+Windows only: The returned function prototype creates functions
+that use the \code{stdcall} calling convention, except on Windows CE
+where \function{WINFUNCTYPE} is the same as \function{CFUNCTYPE}.  The function
+will release the GIL during the call.
+\end{funcdesc}
+
+\begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes}
+The returned function prototype creates functions that use the
+Python calling convention.  The function will \emph{not} release the
+GIL during the call.
+\end{funcdesc}
+
+Function prototypes created by the factory functions can be
+instantiated in different ways, depending on the type and number of
+the parameters in the call.
+
+\begin{funcdescni}{prototype}{address}
+Returns a foreign function at the specified address.
+\end{funcdescni}
+
+\begin{funcdescni}{prototype}{callable}
+Create a C callable function (a callback function) from a Python
+\code{callable}.
+\end{funcdescni}
+
+\begin{funcdescni}{prototype}{func_spec\optional{, paramflags}}
+Returns a foreign function exported by a shared library.
+\code{func{\_}spec} must be a 2-tuple \code{(name{\_}or{\_}ordinal, library)}.
+The first item is the name of the exported function as string, or
+the ordinal of the exported function as small integer.  The second
+item is the shared library instance.
+\end{funcdescni}
+
+\begin{funcdescni}{prototype}{vtbl_index, name\optional{, paramflags\optional{, iid}}}
+Returns a foreign function that will call a COM method.
+\code{vtbl{\_}index} is the index into the virtual function table, a
+small nonnegative integer. \var{name} is name of the COM method.
+\var{iid} is an optional pointer to the interface identifier which
+is used in extended error reporting.
+
+COM methods use a special calling convention: They require a
+pointer to the COM interface as first argument, in addition to
+those parameters that are specified in the \member{argtypes} tuple.
+\end{funcdescni}
+
+The optional \var{paramflags} parameter creates foreign function
+wrappers with much more functionality than the features described
+above.
+
+\var{paramflags} must be a tuple of the same length as \member{argtypes}.
+
+Each item in this tuple contains further information about a
+parameter, it must be a tuple containing 1, 2, or 3 items.
+
+The first item is an integer containing flags for the parameter:
+
+\begin{datadescni}{1}
+Specifies an input parameter to the function.
+\end{datadescni}
+
+\begin{datadescni}{2}
+Output parameter.  The foreign function fills in a value.
+\end{datadescni}
+
+\begin{datadescni}{4}
+Input parameter which defaults to the integer zero.
+\end{datadescni}
+
+The optional second item is the parameter name as string.  If this is
+specified, the foreign function can be called with named parameters.
+
+The optional third item is the default value for this parameter.
+
+This example demonstrates how to wrap the Windows \code{MessageBoxA}
+function so that it supports default parameters and named arguments.
+The C declaration from the windows header file is this:
+\begin{verbatim}
+WINUSERAPI int WINAPI
+MessageBoxA(
+    HWND hWnd ,
+    LPCSTR lpText,
+    LPCSTR lpCaption,
+    UINT uType);
+\end{verbatim}
+
+Here is the wrapping with \code{ctypes}:
+\begin{quote}
+\begin{verbatim}>>> from ctypes import c_int, WINFUNCTYPE, windll
+>>> from ctypes.wintypes import HWND, LPCSTR, UINT
+>>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, c_uint)
+>>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0)
+>>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags)
+>>>\end{verbatim}
+\end{quote}
+
+The MessageBox foreign function can now be called in these ways:
+\begin{verbatim}
+>>> MessageBox()
+>>> MessageBox(text="Spam, spam, spam")
+>>> MessageBox(flags=2, text="foo bar")
+>>>
+\end{verbatim}
+
+A second example demonstrates output parameters.  The win32
+\code{GetWindowRect} function retrieves the dimensions of a specified
+window by copying them into \code{RECT} structure that the caller has to
+supply.  Here is the C declaration:
+\begin{verbatim}
+WINUSERAPI BOOL WINAPI
+GetWindowRect(
+     HWND hWnd,
+     LPRECT lpRect);
+\end{verbatim}
+
+Here is the wrapping with \code{ctypes}:
+\begin{quote}
+\begin{verbatim}>>> from ctypes import POINTER, WINFUNCTYPE, windll
+>>> from ctypes.wintypes import BOOL, HWND, RECT
+>>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
+>>> paramflags = (1, "hwnd"), (2, "lprect")
+>>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
+>>>\end{verbatim}
+\end{quote}
+
+Functions with output parameters will automatically return the output
+parameter value if there is a single one, or a tuple containing the
+output parameter values when there are more than one, so the
+GetWindowRect function now returns a RECT instance, when called.
+
+Output parameters can be combined with the \member{errcheck} protocol to do
+further output processing and error checking.  The win32
+\code{GetWindowRect} api function returns a \code{BOOL} to signal success or
+failure, so this function could do the error checking, and raises an
+exception when the api call failed:
+\begin{verbatim}
+>>> def errcheck(result, func, args):
+...     if not result:
+...         raise WinError()
+...     return args
+>>> GetWindowRect.errcheck = errcheck
+>>>
+\end{verbatim}
+
+If the \member{errcheck} function returns the argument tuple it receives
+unchanged, \code{ctypes} continues the normal processing it does on the
+output parameters.  If you want to return a tuple of window
+coordinates instead of a \code{RECT} instance, you can retrieve the
+fields in the function and return them instead, the normal processing
+will no longer take place:
+\begin{verbatim}
+>>> def errcheck(result, func, args):
+...     if not result:
+...         raise WinError()
+...     rc = args[1]
+...     return rc.left, rc.top, rc.bottom, rc.right
+>>>
+>>> GetWindowRect.errcheck = errcheck
+>>>
+\end{verbatim}
+
+
+\subsubsection{Utility functions\label{ctypes-utility-functions}}
+
+\begin{funcdesc}{addressof}{obj}
+Returns the address of the memory buffer as integer.  \code{obj} must
+be an instance of a ctypes type.
+\end{funcdesc}
+
+\begin{funcdesc}{alignment}{obj_or_type}
+Returns the alignment requirements of a ctypes type.
+\code{obj{\_}or{\_}type} must be a ctypes type or instance.
+\end{funcdesc}
+
+\begin{funcdesc}{byref}{obj}
+Returns a light-weight pointer to \code{obj}, which must be an
+instance of a ctypes type. The returned object can only be used as
+a foreign function call parameter. It behaves similar to
+\code{pointer(obj)}, but the construction is a lot faster.
+\end{funcdesc}
+
+\begin{funcdesc}{cast}{obj, type}
+This function is similar to the cast operator in C. It returns a
+new instance of \code{type} which points to the same memory block as
+\code{obj}. \code{type} must be a pointer type, and \code{obj} must be an
+object that can be interpreted as a pointer.
+\end{funcdesc}
+
+\begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}}
+This function creates a mutable character buffer. The returned
+object is a ctypes array of \class{c{\_}char}.
+
+\code{init{\_}or{\_}size} must be an integer which specifies the size of
+the array, or a string which will be used to initialize the array
+items.
+
+If a string is specified as first argument, the buffer is made one
+item larger than the length of the string so that the last element
+in the array is a NUL termination character. An integer can be
+passed as second argument which allows to specify the size of the
+array if the length of the string should not be used.
+
+If the first parameter is a unicode string, it is converted into
+an 8-bit string according to ctypes conversion rules.
+\end{funcdesc}
+
+\begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}}
+This function creates a mutable unicode character buffer. The
+returned object is a ctypes array of \class{c{\_}wchar}.
+
+\code{init{\_}or{\_}size} must be an integer which specifies the size of
+the array, or a unicode string which will be used to initialize
+the array items.
+
+If a unicode string is specified as first argument, the buffer is
+made one item larger than the length of the string so that the
+last element in the array is a NUL termination character. An
+integer can be passed as second argument which allows to specify
+the size of the array if the length of the string should not be
+used.
+
+If the first parameter is a 8-bit string, it is converted into an
+unicode string according to ctypes conversion rules.
+\end{funcdesc}
+
+\begin{funcdesc}{DllCanUnloadNow}{}
+Windows only: This function is a hook which allows to implement
+inprocess COM servers with ctypes. It is called from the
+DllCanUnloadNow function that the {\_}ctypes extension dll exports.
+\end{funcdesc}
+
+\begin{funcdesc}{DllGetClassObject}{}
+Windows only: This function is a hook which allows to implement
+inprocess COM servers with ctypes. It is called from the
+DllGetClassObject function that the \code{{\_}ctypes} extension dll exports.
+\end{funcdesc}
+
+\begin{funcdesc}{FormatError}{\optional{code}}
+Windows only: Returns a textual description of the error code. If
+no error code is specified, the last error code is used by calling
+the Windows api function GetLastError.
+\end{funcdesc}
+
+\begin{funcdesc}{GetLastError}{}
+Windows only: Returns the last error code set by Windows in the
+calling thread.
+\end{funcdesc}
+
+\begin{funcdesc}{memmove}{dst, src, count}
+Same as the standard C memmove library function: copies \var{count}
+bytes from \code{src} to \var{dst}. \var{dst} and \code{src} must be
+integers or ctypes instances that can be converted to pointers.
+\end{funcdesc}
+
+\begin{funcdesc}{memset}{dst, c, count}
+Same as the standard C memset library function: fills the memory
+block at address \var{dst} with \var{count} bytes of value
+\var{c}. \var{dst} must be an integer specifying an address, or a
+ctypes instance.
+\end{funcdesc}
+
+\begin{funcdesc}{POINTER}{type}
+This factory function creates and returns a new ctypes pointer
+type. Pointer types are cached an reused internally, so calling
+this function repeatedly is cheap. type must be a ctypes type.
+\end{funcdesc}
+
+\begin{funcdesc}{pointer}{obj}
+This function creates a new pointer instance, pointing to
+\code{obj}. The returned object is of the type POINTER(type(obj)).
+
+Note: If you just want to pass a pointer to an object to a foreign
+function call, you should use \code{byref(obj)} which is much faster.
+\end{funcdesc}
+
+\begin{funcdesc}{resize}{obj, size}
+This function resizes the internal memory buffer of obj, which
+must be an instance of a ctypes type. It is not possible to make
+the buffer smaller than the native size of the objects type, as
+given by sizeof(type(obj)), but it is possible to enlarge the
+buffer.
+\end{funcdesc}
+
+\begin{funcdesc}{set_conversion_mode}{encoding, errors}
+This function sets the rules that ctypes objects use when
+converting between 8-bit strings and unicode strings. encoding
+must be a string specifying an encoding, like \code{'utf-8'} or
+\code{'mbcs'}, errors must be a string specifying the error handling
+on encoding/decoding errors. Examples of possible values are
+\code{"strict"}, \code{"replace"}, or \code{"ignore"}.
+
+\code{set{\_}conversion{\_}mode} returns a 2-tuple containing the previous
+conversion rules. On windows, the initial conversion rules are
+\code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}.
+\end{funcdesc}
+
+\begin{funcdesc}{sizeof}{obj_or_type}
+Returns the size in bytes of a ctypes type or instance memory
+buffer. Does the same as the C \code{sizeof()} function.
+\end{funcdesc}
+
+\begin{funcdesc}{string_at}{address\optional{, size}}
+This function returns the string starting at memory address
+address. If size is specified, it is used as size, otherwise the
+string is assumed to be zero-terminated.
+\end{funcdesc}
+
+\begin{funcdesc}{WinError}{code=None, descr=None}
+Windows only: this function is probably the worst-named thing in
+ctypes. It creates an instance of WindowsError. If \var{code} is not
+specified, \code{GetLastError} is called to determine the error
+code. If \code{descr} is not spcified, \function{FormatError} is called to
+get a textual description of the error.
+\end{funcdesc}
+
+\begin{funcdesc}{wstring_at}{address}
+This function returns the wide character string starting at memory
+address \code{address} as unicode string. If \code{size} is specified,
+it is used as the number of characters of the string, otherwise
+the string is assumed to be zero-terminated.
+\end{funcdesc}
+
+
+\subsubsection{Data types\label{ctypes-data-types}}
+
+\begin{classdesc*}{_CData}
+This non-public class is the common base class of all ctypes data
+types.  Among other things, all ctypes type instances contain a
+memory block that hold C compatible data; the address of the
+memory block is returned by the \code{addressof()} helper function.
+Another instance variable is exposed as \member{{\_}objects}; this
+contains other Python objects that need to be kept alive in case
+the memory block contains pointers.
+\end{classdesc*}
+
+Common methods of ctypes data types, these are all class methods (to
+be exact, they are methods of the metaclass):
+
+\begin{methoddesc}{from_address}{address}
+This method returns a ctypes type instance using the memory
+specified by address which must be an integer.
+\end{methoddesc}
+
+\begin{methoddesc}{from_param}{obj}
+This method adapts obj to a ctypes type.  It is called with the
+actual object used in a foreign function call, when the type is
+present in the foreign functions \member{argtypes} tuple; it must
+return an object that can be used as function call parameter.
+
+All ctypes data types have a default implementation of this
+classmethod, normally it returns \code{obj} if that is an instance of
+the type.  Some types accept other objects as well.
+\end{methoddesc}
+
+\begin{methoddesc}{in_dll}{name, library}
+This method returns a ctypes type instance exported by a shared
+library. \var{name} is the name of the symbol that exports the data,
+\code{library} is the loaded shared library.
+\end{methoddesc}
+
+Common instance variables of ctypes data types:
+
+\begin{memberdesc}{_b_base_}
+Sometimes ctypes data instances do not own the memory block they
+contain, instead they share part of the memory block of a base
+object.  The \member{{\_}b{\_}base{\_}} readonly member is the root ctypes
+object that owns the memory block.
+\end{memberdesc}
+
+\begin{memberdesc}{_b_needsfree_}
+This readonly variable is true when the ctypes data instance has
+allocated the memory block itself, false otherwise.
+\end{memberdesc}
+
+\begin{memberdesc}{_objects}
+This member is either \code{None} or a dictionary containing Python
+objects that need to be kept alive so that the memory block
+contents is kept valid.  This object is only exposed for
+debugging; never modify the contents of this dictionary.
+\end{memberdesc}
+
+
+\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}}
+
+\begin{classdesc*}{_SimpleCData}
+This non-public class is the base class of all fundamental ctypes
+data types. It is mentioned here because it contains the common
+attributes of the fundamental ctypes data types.  \code{{\_}SimpleCData}
+is a subclass of \code{{\_}CData}, so it inherits their methods and
+attributes.
+\end{classdesc*}
+
+Instances have a single attribute:
+
+\begin{memberdesc}{value}
+This attribute contains the actual value of the instance. For
+integer and pointer types, it is an integer, for character types,
+it is a single character string, for character pointer types it
+is a Python string or unicode string.
+
+When the \code{value} attribute is retrieved from a ctypes instance,
+usually a new object is returned each time.  \code{ctypes} does \emph{not}
+implement original object return, always a new object is
+constructed.  The same is true for all other ctypes object
+instances.
+\end{memberdesc}
+
+Fundamental data types, when returned as foreign function call
+results, or, for example, by retrieving structure field members or
+array items, are transparently converted to native Python types.  In
+other words, if a foreign function has a \member{restype} of \class{c{\_}char{\_}p},
+you will always receive a Python string, \emph{not} a \class{c{\_}char{\_}p}
+instance.
+
+Subclasses of fundamental data types do \emph{not} inherit this behaviour.
+So, if a foreign functions \member{restype} is a subclass of \class{c{\_}void{\_}p},
+you will receive an instance of this subclass from the function call.
+Of course, you can get the value of the pointer by accessing the
+\code{value} attribute.
+
+These are the fundamental ctypes data types:
+
+\begin{classdesc*}{c_byte}
+Represents the C signed char datatype, and interprets the value as
+small integer. The constructor accepts an optional integer
+initializer; no overflow checking is done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_char}
+Represents the C char datatype, and interprets the value as a single
+character. The constructor accepts an optional string initializer,
+the length of the string must be exactly one character.
+\end{classdesc*}
+
+\begin{classdesc*}{c_char_p}
+Represents the C char * datatype, which must be a pointer to a
+zero-terminated string. The constructor accepts an integer
+address, or a string.
+\end{classdesc*}
+
+\begin{classdesc*}{c_double}
+Represents the C double datatype. The constructor accepts an
+optional float initializer.
+\end{classdesc*}
+
+\begin{classdesc*}{c_float}
+Represents the C double datatype. The constructor accepts an
+optional float initializer.
+\end{classdesc*}
+
+\begin{classdesc*}{c_int}
+Represents the C signed int datatype. The constructor accepts an
+optional integer initializer; no overflow checking is done. On
+platforms where \code{sizeof(int) == sizeof(long)} it is an alias to
+\class{c{\_}long}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_int8}
+Represents the C 8-bit \code{signed int} datatype. Usually an alias for
+\class{c{\_}byte}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_int16}
+Represents the C 16-bit signed int datatype. Usually an alias for
+\class{c{\_}short}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_int32}
+Represents the C 32-bit signed int datatype. Usually an alias for
+\class{c{\_}int}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_int64}
+Represents the C 64-bit \code{signed int} datatype. Usually an alias
+for \class{c{\_}longlong}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_long}
+Represents the C \code{signed long} datatype. The constructor accepts an
+optional integer initializer; no overflow checking is done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_longlong}
+Represents the C \code{signed long long} datatype. The constructor accepts
+an optional integer initializer; no overflow checking is done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_short}
+Represents the C \code{signed short} datatype. The constructor accepts an
+optional integer initializer; no overflow checking is done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_size_t}
+Represents the C \code{size{\_}t} datatype.
+\end{classdesc*}
+
+\begin{classdesc*}{c_ubyte}
+Represents the C \code{unsigned char} datatype, it interprets the
+value as small integer. The constructor accepts an optional
+integer initializer; no overflow checking is done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_uint}
+Represents the C \code{unsigned int} datatype. The constructor accepts an
+optional integer initializer; no overflow checking is done. On
+platforms where \code{sizeof(int) == sizeof(long)} it is an alias for
+\class{c{\_}ulong}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_uint8}
+Represents the C 8-bit unsigned int datatype. Usually an alias for
+\class{c{\_}ubyte}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_uint16}
+Represents the C 16-bit unsigned int datatype. Usually an alias for
+\class{c{\_}ushort}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_uint32}
+Represents the C 32-bit unsigned int datatype. Usually an alias for
+\class{c{\_}uint}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_uint64}
+Represents the C 64-bit unsigned int datatype. Usually an alias for
+\class{c{\_}ulonglong}.
+\end{classdesc*}
+
+\begin{classdesc*}{c_ulong}
+Represents the C \code{unsigned long} datatype. The constructor accepts an
+optional integer initializer; no overflow checking is done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_ulonglong}
+Represents the C \code{unsigned long long} datatype. The constructor
+accepts an optional integer initializer; no overflow checking is
+done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_ushort}
+Represents the C \code{unsigned short} datatype. The constructor accepts an
+optional integer initializer; no overflow checking is done.
+\end{classdesc*}
+
+\begin{classdesc*}{c_void_p}
+Represents the C \code{void *} type. The value is represented as
+integer. The constructor accepts an optional integer initializer.
+\end{classdesc*}
+
+\begin{classdesc*}{c_wchar}
+Represents the C \code{wchar{\_}t} datatype, and interprets the value as a
+single character unicode string. The constructor accepts an
+optional string initializer, the length of the string must be
+exactly one character.
+\end{classdesc*}
+
+\begin{classdesc*}{c_wchar_p}
+Represents the C \code{wchar{\_}t *} datatype, which must be a pointer to
+a zero-terminated wide character string. The constructor accepts
+an integer address, or a string.
+\end{classdesc*}
+
+\begin{classdesc*}{HRESULT}
+Windows only: Represents a \class{HRESULT} value, which contains success
+or error information for a function or method call.
+\end{classdesc*}
+
+\code{py{\_}object} : classdesc*
+\begin{quote}
+
+Represents the C \code{PyObject *} datatype.  Calling this with an
+without an argument creates a \code{NULL} \code{PyObject *} pointer.
+\end{quote}
+
+The \code{ctypes.wintypes} module provides quite some other Windows
+specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}.
+Some useful structures like \code{MSG} or \code{RECT} are also defined.
+
+
+\subsubsection{Structured data types\label{ctypes-structured-data-types}}
+
+\begin{classdesc}{Union}{*args, **kw}
+Abstract base class for unions in native byte order.
+\end{classdesc}
+
+\begin{classdesc}{BigEndianStructure}{*args, **kw}
+Abstract base class for structures in \emph{big endian} byte order.
+\end{classdesc}
+
+\begin{classdesc}{LittleEndianStructure}{*args, **kw}
+Abstract base class for structures in \emph{little endian} byte order.
+\end{classdesc}
+
+Structures with non-native byte order cannot contain pointer type
+fields, or any other data types containing pointer type fields.
+
+\begin{classdesc}{Structure}{*args, **kw}
+Abstract base class for structures in \emph{native} byte order.
+\end{classdesc}
+
+Concrete structure and union types must be created by subclassing one
+of these types, and at least define a \member{{\_}fields{\_}} class variable.
+\code{ctypes} will create descriptors which allow reading and writing the
+fields by direct attribute accesses.  These are the
+
+\begin{memberdesc}{_fields_}
+A sequence defining the structure fields.  The items must be
+2-tuples or 3-tuples.  The first item is the name of the field,
+the second item specifies the type of the field; it can be any
+ctypes data type.
+
+For integer type fields like \class{c{\_}int}, a third optional item can
+be given.  It must be a small positive integer defining the bit
+width of the field.
+
+Field names must be unique within one structure or union.  This is
+not checked, only one field can be accessed when names are
+repeated.
+
+It is possible to define the \member{{\_}fields{\_}} class variable \emph{after}
+the class statement that defines the Structure subclass, this
+allows to create data types that directly or indirectly reference
+themselves:
+\begin{verbatim}
+class List(Structure):
+    pass
+List._fields_ = [("pnext", POINTER(List)),
+                 ...
+                ]
+\end{verbatim}
+
+The \member{{\_}fields{\_}} class variable must, however, be defined before
+the type is first used (an instance is created, \code{sizeof()} is
+called on it, and so on).  Later assignments to the \member{{\_}fields{\_}}
+class variable will raise an AttributeError.
+
+Structure and union subclass constructors accept both positional
+and named arguments.  Positional arguments are used to initialize
+the fields in the same order as they appear in the \member{{\_}fields{\_}}
+definition, named arguments are used to initialize the fields with
+the corresponding name.
+
+It is possible to defined sub-subclasses of structure types, they
+inherit the fields of the base class plus the \member{{\_}fields{\_}} defined
+in the sub-subclass, if any.
+\end{memberdesc}
+
+\begin{memberdesc}{_pack_}
+An optional small integer that allows to override the alignment of
+structure fields in the instance.  \member{{\_}pack{\_}} must already be
+defined when \member{{\_}fields{\_}} is assigned, otherwise it will have no
+effect.
+\end{memberdesc}
+
+\begin{memberdesc}{_anonymous_}
+An optional sequence that lists the names of unnamed (anonymous)
+fields.  \code{{\_}anonymous{\_}} must be already defined when \member{{\_}fields{\_}}
+is assigned, otherwise it will have no effect.
+
+The fields listed in this variable must be structure or union type
+fields.  \code{ctypes} will create descriptors in the structure type
+that allows to access the nested fields directly, without the need
+to create the structure or union field.
+
+Here is an example type (Windows):
+\begin{verbatim}
+class _U(Union):
+    _fields_ = [("lptdesc", POINTER(TYPEDESC)),
+                ("lpadesc", POINTER(ARRAYDESC)),
+                ("hreftype", HREFTYPE)]
+
+class TYPEDESC(Structure):
+    _fields_ = [("u", _U),
+                ("vt", VARTYPE)]
+
+    _anonymous_ = ("u",)
+\end{verbatim}
+
+The \code{TYPEDESC} structure describes a COM data type, the \code{vt}
+field specifies which one of the union fields is valid.  Since the
+\code{u} field is defined as anonymous field, it is now possible to
+access the members directly off the TYPEDESC instance.
+\code{td.lptdesc} and \code{td.u.lptdesc} are equivalent, but the former
+is faster since it does not need to create a temporary union
+instance:
+\begin{verbatim}
+td = TYPEDESC()
+td.vt = VT_PTR
+td.lptdesc = POINTER(some_type)
+td.u.lptdesc = POINTER(some_type)
+\end{verbatim}
+\end{memberdesc}
+
+It is possible to defined sub-subclasses of structures, they inherit
+the fields of the base class.  If the subclass definition has a
+separate \member{{\_}fields{\_}} variable, the fields specified in this are
+appended to the fields of the base class.
+
+Structure and union constructors accept both positional and
+keyword arguments.  Positional arguments are used to initialize member
+fields in the same order as they are appear in \member{{\_}fields{\_}}.  Keyword
+arguments in the constructor are interpreted as attribute assignments,
+so they will initialize \member{{\_}fields{\_}} with the same name, or create new
+attributes for names not present in \member{{\_}fields{\_}}.
+
+
+\subsubsection{Arrays and pointers\label{ctypes-arrays-pointers}}
+
+XXX
+
