Move the 3k reST doc tree in place.
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
new file mode 100644
index 0000000..dc37565
--- /dev/null
+++ b/Doc/library/ctypes.rst
@@ -0,0 +1,2364 @@
+
+:mod:`ctypes` --- A foreign function library for Python.
+========================================================
+
+.. module:: ctypes
+ :synopsis: A foreign function library for Python.
+.. moduleauthor:: Thomas Heller <theller@python.net>
+
+
+.. versionadded:: 2.5
+
+``ctypes`` is a foreign function library for Python. It provides C compatible
+data types, and allows calling functions in dlls/shared libraries. It can be
+used to wrap these libraries in pure Python.
+
+
+.. _ctypes-ctypes-tutorial:
+
+ctypes tutorial
+---------------
+
+Note: The code samples in this tutorial use ``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: Some code sample 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.
+
+
+.. _ctypes-loading-dynamic-link-libraries:
+
+Loading dynamic link libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``ctypes`` exports the *cdll*, and on Windows also *windll* and *oledll* objects
+to load dynamic link libraries.
+
+You load libraries by accessing them as attributes of these objects. *cdll*
+loads libraries which export functions using the standard ``cdecl`` calling
+convention, while *windll* libraries call functions using the ``stdcall``
+calling convention. *oledll* also uses the ``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 ``msvcrt`` is the MS standard C
+library containing most standard C functions, and uses the cdecl calling
+convention::
+
+ >>> 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
+ >>>
+
+Windows appends the usual '.dll' file suffix automatically.
+
+On Linux, it is required to specify the filename *including* the extension to
+load a library, so attribute access does not work. Either the
+:meth:`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::
+
+ >>> 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 ...>
+ >>>
+
+.. % XXX Add section for Mac OS X.
+
+
+.. _ctypes-accessing-functions-from-loaded-dlls:
+
+Accessing functions from loaded dlls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Functions are accessed as attributes of dll objects::
+
+ >>> 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
+ >>>
+
+Note that win32 system dlls like ``kernel32`` and ``user32`` often export ANSI
+as well as UNICODE versions of a function. The UNICODE version is exported with
+an ``W`` appended to the name, while the ANSI version is exported with an ``A``
+appended to the name. The win32 ``GetModuleHandle`` function, which returns a
+*module handle* for a given module name, has the following C prototype, and a
+macro is used to expose one of them as ``GetModuleHandle`` depending on whether
+UNICODE is defined or not::
+
+ /* ANSI version */
+ HMODULE GetModuleHandleA(LPCSTR lpModuleName);
+ /* UNICODE version */
+ HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
+
+*windll* does not try to select one of them by magic, you must access the
+version you need by specifying ``GetModuleHandleA`` or ``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 ``"??2@YAPAXI@Z"``. In this case you have to use ``getattr``
+to retrieve the function::
+
+ >>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS
+ <_FuncPtr object at 0x...>
+ >>>
+
+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::
+
+ >>> 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
+ >>>
+
+
+.. _ctypes-calling-functions:
+
+Calling functions
+^^^^^^^^^^^^^^^^^
+
+You can call these functions like any other Python callable. This example uses
+the ``time()`` function, which returns system time in seconds since the Unix
+epoch, and the ``GetModuleHandleA()`` function, which returns a win32 module
+handle.
+
+This example calls both functions with a NULL pointer (``None`` should be used
+as the NULL pointer)::
+
+ >>> print libc.time(None) # doctest: +SKIP
+ 1150640792
+ >>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS
+ 0x1d000000
+ >>>
+
+``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 *has* been called::
+
+ >>> 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)
+ >>>
+
+The same exception is raised when you call an ``stdcall`` function with the
+``cdecl`` calling convention, or vice versa::
+
+ >>> 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)
+ >>>
+
+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, ``ctypes`` uses win32 structured exception handling to prevent
+crashes from general protection faults when functions are called with invalid
+argument values::
+
+ >>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ WindowsError: exception: access violation reading 0x00000020
+ >>>
+
+There are, however, enough ways to crash Python with ``ctypes``, so you should
+be careful anyway.
+
+``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.
+``None`` is passed as a C ``NULL`` pointer, byte strings and unicode strings are
+passed as pointer to the memory block that contains their data (``char *`` or
+``wchar_t *``). Python integers and Python longs are passed as the platforms
+default C ``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 ``ctypes`` data types.
+
+
+.. _ctypes-fundamental-data-types:
+
+Fundamental data types
+^^^^^^^^^^^^^^^^^^^^^^
+
+``ctypes`` defines a number of primitive C compatible data types :
+
+ +----------------------+--------------------------------+----------------------------+
+ | ctypes type | C type | Python type |
+ +======================+================================+============================+
+ | :class:`c_char` | ``char`` | 1-character string |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_wchar` | ``wchar_t`` | 1-character unicode string |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_byte` | ``char`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ubyte` | ``unsigned char`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_short` | ``short`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ushort` | ``unsigned short`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_int` | ``int`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_uint` | ``unsigned int`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_long` | ``long`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ulong` | ``unsigned long`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_longlong` | ``__int64`` or ``long long`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ulonglong` | ``unsigned __int64`` or | int/long |
+ | | ``unsigned long long`` | |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_float` | ``float`` | float |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_double` | ``double`` | float |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_char_p` | ``char *`` (NUL terminated) | string or ``None`` |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_wchar_p` | ``wchar_t *`` (NUL terminated) | unicode or ``None`` |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_void_p` | ``void *`` | int/long or ``None`` |
+ +----------------------+--------------------------------+----------------------------+
+
+
+All these types can be created by calling them with an optional initializer of
+the correct type and value::
+
+ >>> c_int()
+ c_long(0)
+ >>> c_char_p("Hello, World")
+ c_char_p('Hello, World')
+ >>> c_ushort(-3)
+ c_ushort(65533)
+ >>>
+
+Since these types are mutable, their value can also be changed afterwards::
+
+ >>> i = c_int(42)
+ >>> print i
+ c_long(42)
+ >>> print i.value
+ 42
+ >>> i.value = -99
+ >>> print i.value
+ -99
+ >>>
+
+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 *memory location* they
+point to, *not the contents* of the memory block (of course not, because Python
+strings are immutable)::
+
+ >>> 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
+ >>>
+
+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
+``create_string_buffer`` function which creates these in various ways. The
+current memory block contents can be accessed (or changed) with the ``raw``
+property; if you want to access it as NUL terminated string, use the ``value``
+property::
+
+ >>> 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'
+ >>>
+
+The ``create_string_buffer`` function replaces the ``c_buffer`` function (which
+is still available as an alias), as well as the ``c_string`` function from
+earlier ctypes releases. To create a mutable memory block containing unicode
+characters of the C type ``wchar_t`` use the ``create_unicode_buffer`` function.
+
+
+.. _ctypes-calling-functions-continued:
+
+Calling functions, continued
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Note that printf prints to the real standard output channel, *not* to
+``sys.stdout``, so these examples will only work at the console prompt, not from
+within *IDLE* or *PythonWin*::
+
+ >>> 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
+ >>>
+
+As has been mentioned before, all Python types except integers, strings, and
+unicode strings have to be wrapped in their corresponding ``ctypes`` type, so
+that they can be converted to the required C data type::
+
+ >>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
+ Integer 1234, double 3.1400001049
+ 31
+ >>>
+
+
+.. _ctypes-calling-functions-with-own-custom-data-types:
+
+Calling functions with your own custom data types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also customize ``ctypes`` argument conversion to allow instances of your
+own classes be used as function arguments. ``ctypes`` looks for an
+:attr:`_as_parameter_` attribute and uses this as the function argument. Of
+course, it must be one of integer, string, or unicode::
+
+ >>> 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
+ >>>
+
+If you don't want to store the instance's data in the :attr:`_as_parameter_`
+instance variable, you could define a ``property`` which makes the data
+avaiblable.
+
+
+.. _ctypes-specifying-required-argument-types:
+
+Specifying the required argument types (function prototypes)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to specify the required argument types of functions exported from
+DLLs by setting the :attr:`argtypes` attribute.
+
+:attr:`argtypes` must be a sequence of C data types (the ``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)::
+
+ >>> 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
+ >>>
+
+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::
+
+ >>> 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
+ >>>
+
+If you have defined your own classes which you pass to function calls, you have
+to implement a :meth:`from_param` class method for them to be able to use them
+in the :attr:`argtypes` sequence. The :meth:`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 :attr:`_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 ``ctypes`` instance, or something having the
+:attr:`_as_parameter_` attribute.
+
+
+.. _ctypes-return-types:
+
+Return types
+^^^^^^^^^^^^
+
+By default functions are assumed to return the C ``int`` type. Other return
+types can be specified by setting the :attr:`restype` attribute of the function
+object.
+
+Here is a more advanced example, it uses the ``strchr`` function, which expects
+a string pointer and a char, and returns a pointer to a string::
+
+ >>> 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
+ >>>
+
+If you want to avoid the ``ord("x")`` calls above, you can set the
+:attr:`argtypes` attribute, and the second argument will be converted from a
+single character Python string into a C char::
+
+ >>> 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'
+ >>>
+
+You can also use a callable Python object (a function or a class for example) as
+the :attr:`restype` attribute, if the foreign function returns an integer. The
+callable will be called with the ``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::
+
+ >>> 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.
+ >>>
+
+``WinError`` is a function which will call Windows ``FormatMessage()`` api to
+get the string representation of an error code, and *returns* an exception.
+``WinError`` takes an optional error code parameter, if no one is used, it calls
+:func:`GetLastError` to retrieve it.
+
+Please note that a much more powerful error checking mechanism is available
+through the :attr:`errcheck` attribute; see the reference manual for details.
+
+
+.. _ctypes-passing-pointers:
+
+Passing pointers (or: passing parameters by reference)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes a C api function expects a *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 *passing parameters by reference*.
+
+``ctypes`` exports the :func:`byref` function which is used to pass parameters
+by reference. The same effect can be achieved with the ``pointer`` function,
+although ``pointer`` does a lot more work since it constructs a real pointer
+object, so it is faster to use :func:`byref` if you don't need the pointer
+object in Python itself::
+
+ >>> 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'
+ >>>
+
+
+.. _ctypes-structures-unions:
+
+Structures and unions
+^^^^^^^^^^^^^^^^^^^^^
+
+Structures and unions must derive from the :class:`Structure` and :class:`Union`
+base classes which are defined in the ``ctypes`` module. Each subclass must
+define a :attr:`_fields_` attribute. :attr:`_fields_` must be a list of
+*2-tuples*, containing a *field name* and a *field type*.
+
+The field type must be a ``ctypes`` type like :class:`c_int`, or any other
+derived ``ctypes`` type: structure, union, array, pointer.
+
+Here is a simple example of a POINT structure, which contains two integers named
+``x`` and ``y``, and also shows how to initialize a structure in the
+constructor::
+
+ >>> 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
+ >>>
+
+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 ``upperleft`` and
+``lowerright`` ::
+
+ >>> 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
+ >>>
+
+Nested structures can also be initialized in the constructor in several ways::
+
+ >>> r = RECT(POINT(1, 2), POINT(3, 4))
+ >>> r = RECT((1, 2), (3, 4))
+
+Fields descriptors can be retrieved from the *class*, they are useful for
+debugging because they can provide useful information::
+
+ >>> print POINT.x
+ <Field type=c_long, ofs=0, size=4>
+ >>> print POINT.y
+ <Field type=c_long, ofs=4, size=4>
+ >>>
+
+
+.. _ctypes-structureunion-alignment-byte-order:
+
+Structure/union alignment and 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
+:attr:`_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 ``#pragma pack(n)`` also does in MSVC.
+
+``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.
+
+
+.. _ctypes-bit-fields-in-structures-unions:
+
+Bit fields in structures and 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 :attr:`_fields_` tuples::
+
+ >>> 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>
+ >>>
+
+
+.. _ctypes-arrays:
+
+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::
+
+ TenPointsArrayType = POINT * 10
+
+Here is an example of an somewhat artifical data type, a structure containing 4
+POINTs among other stuff::
+
+ >>> 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
+ >>>
+
+Instances are created in the usual way, by calling the class::
+
+ arr = TenPointsArrayType()
+ for pt in arr:
+ print pt.x, pt.y
+
+The above code print a series of ``0 0`` lines, because the array contents is
+initialized to zeros.
+
+Initializers of the correct type can also be specified::
+
+ >>> 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
+ >>>
+
+
+.. _ctypes-pointers:
+
+Pointers
+^^^^^^^^
+
+Pointer instances are created by calling the ``pointer`` function on a
+``ctypes`` type::
+
+ >>> from ctypes import *
+ >>> i = c_int(42)
+ >>> pi = pointer(i)
+ >>>
+
+Pointer instances have a ``contents`` attribute which returns the object to
+which the pointer points, the ``i`` object above::
+
+ >>> pi.contents
+ c_long(42)
+ >>>
+
+Note that ``ctypes`` does not have OOR (original object return), it constructs a
+new, equivalent object each time you retrieve an attribute::
+
+ >>> pi.contents is i
+ False
+ >>> pi.contents is pi.contents
+ False
+ >>>
+
+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::
+
+ >>> i = c_int(99)
+ >>> pi.contents = i
+ >>> pi.contents
+ c_long(99)
+ >>>
+
+Pointer instances can also be indexed with integers::
+
+ >>> pi[0]
+ 99
+ >>>
+
+Assigning to an integer index changes the pointed to value::
+
+ >>> print i
+ c_long(99)
+ >>> pi[0] = 22
+ >>> print i
+ c_long(22)
+ >>>
+
+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 *know* that the pointer actually points to an array instead of a single
+item.
+
+Behind the scenes, the ``pointer`` function does more than simply create pointer
+instances, it has to create pointer *types* first. This is done with the
+``POINTER`` function, which accepts any ``ctypes`` type, and returns a new
+type::
+
+ >>> 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...>
+ >>>
+
+Calling the pointer type without an argument creates a ``NULL`` pointer.
+``NULL`` pointers have a ``False`` boolean value::
+
+ >>> null_ptr = POINTER(c_int)()
+ >>> print bool(null_ptr)
+ False
+ >>>
+
+``ctypes`` checks for ``NULL`` when dereferencing pointers (but dereferencing
+non-\ ``NULL`` pointers would crash Python)::
+
+ >>> 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
+ >>>
+
+
+.. _ctypes-type-conversions:
+
+Type conversions
+^^^^^^^^^^^^^^^^
+
+Usually, ctypes does strict type checking. This means, if you have
+``POINTER(c_int)`` in the :attr:`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 ``POINTER(c_int)``, ctypes accepts an array of c_int::
+
+ >>> 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
+ >>>
+
+To set a POINTER type field to ``NULL``, you can assign ``None``::
+
+ >>> bar.values = None
+ >>>
+
+XXX list other conversions...
+
+Sometimes you have instances of incompatible types. In ``C``, you can cast one
+type into another type. ``ctypes`` provides a ``cast`` function which can be
+used in the same way. The ``Bar`` structure defined above accepts
+``POINTER(c_int)`` pointers or :class:`c_int` arrays for its ``values`` field,
+but not instances of other types::
+
+ >>> 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
+ >>>
+
+For these cases, the ``cast`` function is handy.
+
+The ``cast`` function can be used to cast a ctypes instance into a pointer to a
+different ctypes data type. ``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::
+
+ >>> a = (c_byte * 4)()
+ >>> cast(a, POINTER(c_int))
+ <ctypes.LP_c_long object at ...>
+ >>>
+
+So, ``cast`` can be used to assign to the ``values`` field of ``Bar`` the
+structure::
+
+ >>> bar = Bar()
+ >>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
+ >>> print bar.values[0]
+ 0
+ >>>
+
+
+.. _ctypes-incomplete-types:
+
+Incomplete Types
+^^^^^^^^^^^^^^^^
+
+*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::
+
+ struct cell; /* forward declaration */
+
+ struct {
+ char *name;
+ struct cell *next;
+ } cell;
+
+The straightforward translation into ctypes code would be this, but it does not
+work::
+
+ >>> 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
+ >>>
+
+because the new ``class cell`` is not available in the class statement itself.
+In ``ctypes``, we can define the ``cell`` class and set the :attr:`_fields_`
+attribute later, after the class statement::
+
+ >>> from ctypes import *
+ >>> class cell(Structure):
+ ... pass
+ ...
+ >>> cell._fields_ = [("name", c_char_p),
+ ... ("next", POINTER(cell))]
+ >>>
+
+Lets try it. We create two instances of ``cell``, and let them point to each
+other, and finally follow the pointer chain a few times::
+
+ >>> 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
+ >>>
+
+
+.. _ctypes-callback-functions:
+
+Callback functions
+^^^^^^^^^^^^^^^^^^
+
+``ctypes`` allows to create C callable function pointers from Python callables.
+These are sometimes called *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 :func:`qsort`
+function, this is used to sort items with the help of a callback function.
+:func:`qsort` will be used to sort an array of integers::
+
+ >>> IntArray5 = c_int * 5
+ >>> ia = IntArray5(5, 1, 7, 33, 99)
+ >>> qsort = libc.qsort
+ >>> qsort.restype = None
+ >>>
+
+:func:`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 ``type`` for the callback function::
+
+ >>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
+ >>>
+
+For the first implementation of the callback function, we simply print the
+arguments we get, and return 0 (incremental development ;-)::
+
+ >>> def py_cmp_func(a, b):
+ ... print "py_cmp_func", a, b
+ ... return 0
+ ...
+ >>>
+
+Create the C callable callback::
+
+ >>> cmp_func = CMPFUNC(py_cmp_func)
+ >>>
+
+And we're ready to go::
+
+ >>> 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...>
+ >>>
+
+We know how to access the contents of a pointer, so lets redefine our callback::
+
+ >>> def py_cmp_func(a, b):
+ ... print "py_cmp_func", a[0], b[0]
+ ... return 0
+ ...
+ >>> cmp_func = CMPFUNC(py_cmp_func)
+ >>>
+
+Here is what we get on Windows::
+
+ >>> 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
+ >>>
+
+It is funny to see that on linux the sort function seems to work much more
+efficient, it is doing less comparisons::
+
+ >>> 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
+ >>>
+
+Ah, we're nearly done! The last step is to actually compare the two items and
+return a useful result::
+
+ >>> def py_cmp_func(a, b):
+ ... print "py_cmp_func", a[0], b[0]
+ ... return a[0] - b[0]
+ ...
+ >>>
+
+Final run on Windows::
+
+ >>> 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
+ >>>
+
+and on Linux::
+
+ >>> 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
+ >>>
+
+It is quite interesting to see that the Windows :func:`qsort` function needs
+more comparisons than the linux version!
+
+As we can easily check, our array is sorted now::
+
+ >>> for i in ia: print i,
+ ...
+ 1 5 7 33 99
+ >>>
+
+**Important note for callback functions:**
+
+Make sure you keep references to CFUNCTYPE objects as long as they are used from
+C code. ``ctypes`` doesn't, and if you don't, they may be garbage collected,
+crashing your program when a callback is made.
+
+
+.. _ctypes-accessing-values-exported-from-dlls:
+
+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 ``Py_OptimizeFlag``, an integer set
+to 0, 1, or 2, depending on the :option:`-O` or :option:`-OO` flag given on
+startup.
+
+``ctypes`` can access values like this with the :meth:`in_dll` class methods of
+the type. *pythonapi* is a predefined symbol giving access to the Python C
+api::
+
+ >>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
+ >>> print opt_flag
+ c_long(0)
+ >>>
+
+If the interpreter would have been started with :option:`-O`, the sample would
+have printed ``c_long(1)``, or ``c_long(2)`` if :option:`-OO` would have been
+specified.
+
+An extended example which also demonstrates the use of pointers accesses the
+``PyImport_FrozenModules`` pointer exported by Python.
+
+Quoting the Python docs: *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 ``ctypes``::
+
+ >>> from ctypes import *
+ >>>
+ >>> class struct_frozen(Structure):
+ ... _fields_ = [("name", c_char_p),
+ ... ("code", POINTER(c_ubyte)),
+ ... ("size", c_int)]
+ ...
+ >>>
+
+We have defined the ``struct _frozen`` data type, so we can get the pointer to
+the table::
+
+ >>> FrozenTable = POINTER(struct_frozen)
+ >>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
+ >>>
+
+Since ``table`` is a ``pointer`` to the array of ``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::
+
+ >>> for item in table:
+ ... print item.name, item.size
+ ... if item.name is None:
+ ... break
+ ...
+ __hello__ 104
+ __phello__ -104
+ __phello__.spam 104
+ None 0
+ >>>
+
+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 ``import __hello__`` for example.
+
+
+.. _ctypes-surprises:
+
+Surprises
+^^^^^^^^^
+
+There are some edges in ``ctypes`` where you may be expect something else than
+what actually happens.
+
+Consider the following example::
+
+ >>> 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
+ >>>
+
+Hm. We certainly expected the last statement to print ``3 4 1 2``. What
+happended? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above::
+
+ >>> temp0, temp1 = rc.b, rc.a
+ >>> rc.a = temp0
+ >>> rc.b = temp1
+ >>>
+
+Note that ``temp0`` and ``temp1`` are objects still using the internal buffer of
+the ``rc`` object above. So executing ``rc.a = temp0`` copies the buffer
+contents of ``temp0`` into ``rc`` 's buffer. This, in turn, changes the
+contents of ``temp1``. So, the last assignment ``rc.b = temp1``, doesn't have
+the expected effect.
+
+Keep in mind that retrieving subobjects from Structure, Unions, and Arrays
+doesn't *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::
+
+ >>> s = c_char_p()
+ >>> s.value = "abc def ghi"
+ >>> s.value
+ 'abc def ghi'
+ >>> s.value is s.value
+ False
+ >>>
+
+Why is it printing ``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
+``contents`` of the object is stored. Accessing the contents again constructs a
+new Python each time!
+
+
+.. _ctypes-variable-sized-data-types:
+
+Variable-sized data types
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``ctypes`` provides some support for variable-sized arrays and structures (this
+was added in version 0.9.9.7).
+
+The ``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
+``ValueError`` is raised if this is tried::
+
+ >>> 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
+ >>>
+
+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::
+
+ >>> short_array[:]
+ [0, 0, 0, 0]
+ >>> short_array[7]
+ Traceback (most recent call last):
+ ...
+ IndexError: invalid index
+ >>>
+
+Another way to use variable-sized data types with ``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.
+
+
+.. _ctypes-bugs-todo-non-implemented-things:
+
+Bugs, ToDo and non-implemented things
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enumeration types are not implemented. You can do it easily yourself, using
+:class:`c_int` as the base class.
+
+``long double`` is not implemented.
+
+.. % Local Variables:
+.. % compile-command: "make.bat"
+.. % End:
+
+
+.. _ctypes-ctypes-reference:
+
+ctypes reference
+----------------
+
+
+.. _ctypes-finding-shared-libraries:
+
+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 ``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 ``ctypes.util`` module provides a function which can help to determine the
+library to load.
+
+
+.. data:: find_library(name)
+ :noindex:
+
+ Try to find a library and return a pathname. *name* is the library name without
+ any prefix like *lib*, suffix like ``.so``, ``.dylib`` or version number (this
+ is the form used for the posix linker option :option:`-l`). If no library can
+ be found, returns ``None``.
+
+The exact functionality is system dependend.
+
+On Linux, ``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::
+
+ >>> 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'
+ >>>
+
+On OS X, ``find_library`` tries several predefined naming schemes and paths to
+locate the library, and returns a full pathname if successfull::
+
+ >>> 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'
+ >>>
+
+On Windows, ``find_library`` searches along the system search path, and returns
+the full pathname, but since there is no predefined naming scheme a call like
+``find_library("c")`` will fail and return ``None``.
+
+If wrapping a shared library with ``ctypes``, it *may* be better to determine
+the shared library name at development type, and hardcode that into the wrapper
+module instead of using ``find_library`` to locate the library at runtime.
+
+
+.. _ctypes-loading-shared-libraries:
+
+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:
+
+
+.. class:: 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
+ ``int``.
+
+
+.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None)
+
+ Windows only: Instances of this class represent loaded shared libraries,
+ functions in these libraries use the ``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.
+
+
+.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None)
+
+ Windows only: Instances of this class represent loaded shared libraries,
+ functions in these libraries use the ``stdcall`` calling convention, and are
+ assumed to return ``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.
+
+The Python GIL is released before calling any function exported by these
+libraries, and reaquired afterwards.
+
+
+.. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None)
+
+ Instances of this class behave like :class:`CDLL` instances, except that the
+ Python GIL is *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.
+
+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 ``handle`` named
+parameter, otherwise the underlying platforms ``dlopen`` or :meth:`LoadLibrary`
+function is used to load the library into the process, and to get a handle to
+it.
+
+The *mode* parameter can be used to specify how the library is loaded. For
+details, consult the ``dlopen(3)`` manpage, on Windows, *mode* is ignored.
+
+
+.. data:: RTLD_GLOBAL
+ :noindex:
+
+ Flag to use as *mode* parameter. On platforms where this flag is not available,
+ it is defined as the integer zero.
+
+
+.. data:: RTLD_LOCAL
+ :noindex:
+
+ Flag to use as *mode* parameter. On platforms where this is not available, it
+ is the same as *RTLD_GLOBAL*.
+
+
+.. data:: DEFAULT_MODE
+ :noindex:
+
+ The default mode which is used to load shared libraries. On OSX 10.3, this is
+ *RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*.
+
+Instances of these classes have no public methods, however :meth:`__getattr__`
+and :meth:`__getitem__` have special behaviour: functions exported by the shared
+library can be accessed as attributes of by index. Please note that both
+:meth:`__getattr__` and :meth:`__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:
+
+
+.. attribute:: PyDLL._handle
+
+ The system handle used to access the library.
+
+
+.. attribute:: PyDLL._name
+
+ The name of the library passed in the contructor.
+
+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
+:meth:`LoadLibrary` method, or by retrieving the library as attribute of the
+loader instance.
+
+
+.. class:: LibraryLoader(dlltype)
+
+ Class which loads shared libraries. ``dlltype`` should be one of the
+ :class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types.
+
+ :meth:`__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.
+
+
+.. method:: LibraryLoader.LoadLibrary(name)
+
+ Load a shared library into the process and return it. This method always
+ returns a new instance of the library.
+
+These prefabricated library loaders are available:
+
+
+.. data:: cdll
+ :noindex:
+
+ Creates :class:`CDLL` instances.
+
+
+.. data:: windll
+ :noindex:
+
+ Windows only: Creates :class:`WinDLL` instances.
+
+
+.. data:: oledll
+ :noindex:
+
+ Windows only: Creates :class:`OleDLL` instances.
+
+
+.. data:: pydll
+ :noindex:
+
+ Creates :class:`PyDLL` instances.
+
+For accessing the C Python api directly, a ready-to-use Python shared library
+object is available:
+
+
+.. data:: pythonapi
+ :noindex:
+
+ An instance of :class:`PyDLL` that exposes Python C api functions as attributes.
+ Note that all these functions are assumed to return C ``int``, which is of
+ course not always the truth, so you have to assign the correct :attr:`restype`
+ attribute to use these functions.
+
+
+.. _ctypes-foreign-functions:
+
+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:
+
+
+.. class:: _FuncPtr
+
+ Base class for C callable foreign functions.
+
+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.
+
+
+.. attribute:: _FuncPtr.restype
+
+ Assign a ctypes type to specify the result type of the foreign function. Use
+ ``None`` for ``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 ``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 :attr:`restype` and assign a callable to the
+ :attr:`errcheck` attribute.
+
+
+.. attribute:: _FuncPtr.argtypes
+
+ Assign a tuple of ctypes types to specify the argument types that the function
+ accepts. Functions using the ``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
+ :meth:`from_param` class method of the items in the :attr:`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 :attr:`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 :meth:`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.
+
+
+.. attribute:: _FuncPtr.errcheck
+
+ Assign a Python function or another callable to this attribute. The callable
+ will be called with three or more arguments:
+
+
+.. function:: callable(result, func, arguments)
+ :noindex:
+
+ ``result`` is what the foreign function returns, as specified by the
+ :attr:`restype` attribute.
+
+ ``func`` is the foreign function object itself, this allows to reuse the same
+ callable object to check or postprocess the results of several functions.
+
+ ``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.
+
+
+.. exception:: ArgumentError()
+
+ This exception is raised when a foreign function call cannot convert one of the
+ passed arguments.
+
+
+.. _ctypes-function-prototypes:
+
+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.
+
+
+.. function:: 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.
+
+
+.. function:: WINFUNCTYPE(restype, *argtypes)
+
+ Windows only: The returned function prototype creates functions that use the
+ ``stdcall`` calling convention, except on Windows CE where :func:`WINFUNCTYPE`
+ is the same as :func:`CFUNCTYPE`. The function will release the GIL during the
+ call.
+
+
+.. function:: PYFUNCTYPE(restype, *argtypes)
+
+ The returned function prototype creates functions that use the Python calling
+ convention. The function will *not* release the GIL during the call.
+
+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.
+
+
+.. function:: prototype(address)
+ :noindex:
+
+ Returns a foreign function at the specified address.
+
+
+.. function:: prototype(callable)
+ :noindex:
+
+ Create a C callable function (a callback function) from a Python ``callable``.
+
+
+.. function:: prototype(func_spec[, paramflags])
+ :noindex:
+
+ Returns a foreign function exported by a shared library. ``func_spec`` must be a
+ 2-tuple ``(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.
+
+
+.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
+ :noindex:
+
+ Returns a foreign function that will call a COM method. ``vtbl_index`` is the
+ index into the virtual function table, a small nonnegative integer. *name* is
+ name of the COM method. *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 :attr:`argtypes` tuple.
+
+The optional *paramflags* parameter creates foreign function wrappers with much
+more functionality than the features described above.
+
+*paramflags* must be a tuple of the same length as :attr:`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:
+
+
+.. data:: 1
+ :noindex:
+
+ Specifies an input parameter to the function.
+
+
+.. data:: 2
+ :noindex:
+
+ Output parameter. The foreign function fills in a value.
+
+
+.. data:: 4
+ :noindex:
+
+ Input parameter which defaults to the integer zero.
+
+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 ``MessageBoxA`` function so
+that it supports default parameters and named arguments. The C declaration from
+the windows header file is this::
+
+ WINUSERAPI int WINAPI
+ MessageBoxA(
+ HWND hWnd ,
+ LPCSTR lpText,
+ LPCSTR lpCaption,
+ UINT uType);
+
+Here is the wrapping with ``ctypes``:
+
+ ::
+
+ >>> from ctypes import c_int, WINFUNCTYPE, windll
+ >>> from ctypes.wintypes import HWND, LPCSTR, UINT
+ >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT)
+ >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0)
+ >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags)
+ >>>
+
+The MessageBox foreign function can now be called in these ways::
+
+ >>> MessageBox()
+ >>> MessageBox(text="Spam, spam, spam")
+ >>> MessageBox(flags=2, text="foo bar")
+ >>>
+
+A second example demonstrates output parameters. The win32 ``GetWindowRect``
+function retrieves the dimensions of a specified window by copying them into
+``RECT`` structure that the caller has to supply. Here is the C declaration::
+
+ WINUSERAPI BOOL WINAPI
+ GetWindowRect(
+ HWND hWnd,
+ LPRECT lpRect);
+
+Here is the wrapping with ``ctypes``:
+
+ ::
+
+ >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
+ >>> from ctypes.wintypes import BOOL, HWND, RECT
+ >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
+ >>> paramflags = (1, "hwnd"), (2, "lprect")
+ >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
+ >>>
+
+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 :attr:`errcheck` protocol to do
+further output processing and error checking. The win32 ``GetWindowRect`` api
+function returns a ``BOOL`` to signal success or failure, so this function could
+do the error checking, and raises an exception when the api call failed::
+
+ >>> def errcheck(result, func, args):
+ ... if not result:
+ ... raise WinError()
+ ... return args
+ >>> GetWindowRect.errcheck = errcheck
+ >>>
+
+If the :attr:`errcheck` function returns the argument tuple it receives
+unchanged, ``ctypes`` continues the normal processing it does on the output
+parameters. If you want to return a tuple of window coordinates instead of a
+``RECT`` instance, you can retrieve the fields in the function and return them
+instead, the normal processing will no longer take place::
+
+ >>> 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
+ >>>
+
+
+.. _ctypes-utility-functions:
+
+Utility functions
+^^^^^^^^^^^^^^^^^
+
+
+.. function:: addressof(obj)
+
+ Returns the address of the memory buffer as integer. ``obj`` must be an
+ instance of a ctypes type.
+
+
+.. function:: alignment(obj_or_type)
+
+ Returns the alignment requirements of a ctypes type. ``obj_or_type`` must be a
+ ctypes type or instance.
+
+
+.. function:: byref(obj)
+
+ Returns a light-weight pointer to ``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 ``pointer(obj)``, but the construction is a lot faster.
+
+
+.. function:: cast(obj, type)
+
+ This function is similar to the cast operator in C. It returns a new instance of
+ ``type`` which points to the same memory block as ``obj``. ``type`` must be a
+ pointer type, and ``obj`` must be an object that can be interpreted as a
+ pointer.
+
+
+.. function:: create_string_buffer(init_or_size[, size])
+
+ This function creates a mutable character buffer. The returned object is a
+ ctypes array of :class:`c_char`.
+
+ ``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.
+
+
+.. function:: create_unicode_buffer(init_or_size[, size])
+
+ This function creates a mutable unicode character buffer. The returned object is
+ a ctypes array of :class:`c_wchar`.
+
+ ``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.
+
+
+.. function:: 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.
+
+
+.. function:: 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
+ ``_ctypes`` extension dll exports.
+
+
+.. function:: FormatError([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.
+
+
+.. function:: GetLastError()
+
+ Windows only: Returns the last error code set by Windows in the calling thread.
+
+
+.. function:: memmove(dst, src, count)
+
+ Same as the standard C memmove library function: copies *count* bytes from
+ ``src`` to *dst*. *dst* and ``src`` must be integers or ctypes instances that
+ can be converted to pointers.
+
+
+.. function:: memset(dst, c, count)
+
+ Same as the standard C memset library function: fills the memory block at
+ address *dst* with *count* bytes of value *c*. *dst* must be an integer
+ specifying an address, or a ctypes instance.
+
+
+.. function:: 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.
+
+
+.. function:: pointer(obj)
+
+ This function creates a new pointer instance, pointing to ``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 ``byref(obj)`` which is much faster.
+
+
+.. function:: 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.
+
+
+.. function:: 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 ``'utf-8'`` or ``'mbcs'``, errors must be a string specifying the
+ error handling on encoding/decoding errors. Examples of possible values are
+ ``"strict"``, ``"replace"``, or ``"ignore"``.
+
+ ``set_conversion_mode`` returns a 2-tuple containing the previous conversion
+ rules. On windows, the initial conversion rules are ``('mbcs', 'ignore')``, on
+ other systems ``('ascii', 'strict')``.
+
+
+.. function:: sizeof(obj_or_type)
+
+ Returns the size in bytes of a ctypes type or instance memory buffer. Does the
+ same as the C ``sizeof()`` function.
+
+
+.. function:: string_at(address[, 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.
+
+
+.. function:: WinError(code=None, descr=None)
+
+ Windows only: this function is probably the worst-named thing in ctypes. It
+ creates an instance of WindowsError. If *code* is not specified,
+ ``GetLastError`` is called to determine the error code. If ``descr`` is not
+ spcified, :func:`FormatError` is called to get a textual description of the
+ error.
+
+
+.. function:: wstring_at(address)
+
+ This function returns the wide character string starting at memory address
+ ``address`` as unicode string. If ``size`` is specified, it is used as the
+ number of characters of the string, otherwise the string is assumed to be
+ zero-terminated.
+
+
+.. _ctypes-data-types:
+
+Data types
+^^^^^^^^^^
+
+
+.. class:: _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
+ ``addressof()`` helper function. Another instance variable is exposed as
+ :attr:`_objects`; this contains other Python objects that need to be kept alive
+ in case the memory block contains pointers.
+
+Common methods of ctypes data types, these are all class methods (to be exact,
+they are methods of the metaclass):
+
+
+.. method:: _CData.from_address(address)
+
+ This method returns a ctypes type instance using the memory specified by address
+ which must be an integer.
+
+
+.. method:: _CData.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 :attr:`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 ``obj`` if that is an instance of the type. Some types
+ accept other objects as well.
+
+
+.. method:: _CData.in_dll(library, name)
+
+ This method returns a ctypes type instance exported by a shared library. *name*
+ is the name of the symbol that exports the data, *library* is the loaded shared
+ library.
+
+Common instance variables of ctypes data types:
+
+
+.. attribute:: _CData._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
+ :attr:`_b_base_` readonly member is the root ctypes object that owns the memory
+ block.
+
+
+.. attribute:: _CData._b_needsfree_
+
+ This readonly variable is true when the ctypes data instance has allocated the
+ memory block itself, false otherwise.
+
+
+.. attribute:: _CData._objects
+
+ This member is either ``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.
+
+
+.. _ctypes-fundamental-data-types-2:
+
+Fundamental data types
+^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: _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. ``_SimpleCData`` is a subclass of ``_CData``, so it inherits
+ their methods and attributes.
+
+Instances have a single attribute:
+
+
+.. attribute:: _SimpleCData.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 ``value`` attribute is retrieved from a ctypes instance, usually a new
+ object is returned each time. ``ctypes`` does *not* implement original object
+ return, always a new object is constructed. The same is true for all other
+ ctypes object instances.
+
+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
+:attr:`restype` of :class:`c_char_p`, you will always receive a Python string,
+*not* a :class:`c_char_p` instance.
+
+Subclasses of fundamental data types do *not* inherit this behaviour. So, if a
+foreign functions :attr:`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 ``value`` attribute.
+
+These are the fundamental ctypes data types:
+
+
+.. class:: 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.
+
+
+.. class:: 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.
+
+
+.. class:: 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.
+
+
+.. class:: c_double
+
+ Represents the C double datatype. The constructor accepts an optional float
+ initializer.
+
+
+.. class:: c_float
+
+ Represents the C double datatype. The constructor accepts an optional float
+ initializer.
+
+
+.. class:: c_int
+
+ Represents the C signed int datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done. On platforms where
+ ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`.
+
+
+.. class:: c_int8
+
+ Represents the C 8-bit ``signed int`` datatype. Usually an alias for
+ :class:`c_byte`.
+
+
+.. class:: c_int16
+
+ Represents the C 16-bit signed int datatype. Usually an alias for
+ :class:`c_short`.
+
+
+.. class:: c_int32
+
+ Represents the C 32-bit signed int datatype. Usually an alias for
+ :class:`c_int`.
+
+
+.. class:: c_int64
+
+ Represents the C 64-bit ``signed int`` datatype. Usually an alias for
+ :class:`c_longlong`.
+
+
+.. class:: c_long
+
+ Represents the C ``signed long`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done.
+
+
+.. class:: c_longlong
+
+ Represents the C ``signed long long`` datatype. The constructor accepts an
+ optional integer initializer; no overflow checking is done.
+
+
+.. class:: c_short
+
+ Represents the C ``signed short`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done.
+
+
+.. class:: c_size_t
+
+ Represents the C ``size_t`` datatype.
+
+
+.. class:: c_ubyte
+
+ Represents the C ``unsigned char`` datatype, it interprets the value as small
+ integer. The constructor accepts an optional integer initializer; no overflow
+ checking is done.
+
+
+.. class:: c_uint
+
+ Represents the C ``unsigned int`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done. On platforms where
+ ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`.
+
+
+.. class:: c_uint8
+
+ Represents the C 8-bit unsigned int datatype. Usually an alias for
+ :class:`c_ubyte`.
+
+
+.. class:: c_uint16
+
+ Represents the C 16-bit unsigned int datatype. Usually an alias for
+ :class:`c_ushort`.
+
+
+.. class:: c_uint32
+
+ Represents the C 32-bit unsigned int datatype. Usually an alias for
+ :class:`c_uint`.
+
+
+.. class:: c_uint64
+
+ Represents the C 64-bit unsigned int datatype. Usually an alias for
+ :class:`c_ulonglong`.
+
+
+.. class:: c_ulong
+
+ Represents the C ``unsigned long`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done.
+
+
+.. class:: c_ulonglong
+
+ Represents the C ``unsigned long long`` datatype. The constructor accepts an
+ optional integer initializer; no overflow checking is done.
+
+
+.. class:: c_ushort
+
+ Represents the C ``unsigned short`` datatype. The constructor accepts an
+ optional integer initializer; no overflow checking is done.
+
+
+.. class:: c_void_p
+
+ Represents the C ``void *`` type. The value is represented as integer. The
+ constructor accepts an optional integer initializer.
+
+
+.. class:: c_wchar
+
+ Represents the C ``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.
+
+
+.. class:: c_wchar_p
+
+ Represents the C ``wchar_t *`` datatype, which must be a pointer to a
+ zero-terminated wide character string. The constructor accepts an integer
+ address, or a string.
+
+
+.. class:: c_bool
+
+ Represent the C ``bool`` datatype (more accurately, _Bool from C99). Its value
+ can be True or False, and the constructor accepts any object that has a truth
+ value.
+
+ .. versionadded:: 2.6
+
+
+.. class:: HRESULT
+
+ Windows only: Represents a :class:`HRESULT` value, which contains success or
+ error information for a function or method call.
+
+
+.. class:: py_object
+
+ Represents the C ``PyObject *`` datatype. Calling this without an argument
+ creates a ``NULL`` ``PyObject *`` pointer.
+
+The ``ctypes.wintypes`` module provides quite some other Windows specific data
+types, for example ``HWND``, ``WPARAM``, or ``DWORD``. Some useful structures
+like ``MSG`` or ``RECT`` are also defined.
+
+
+.. _ctypes-structured-data-types:
+
+Structured data types
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: Union(*args, **kw)
+
+ Abstract base class for unions in native byte order.
+
+
+.. class:: BigEndianStructure(*args, **kw)
+
+ Abstract base class for structures in *big endian* byte order.
+
+
+.. class:: LittleEndianStructure(*args, **kw)
+
+ Abstract base class for structures in *little endian* byte order.
+
+Structures with non-native byte order cannot contain pointer type fields, or any
+other data types containing pointer type fields.
+
+
+.. class:: Structure(*args, **kw)
+
+ Abstract base class for structures in *native* byte order.
+
+Concrete structure and union types must be created by subclassing one of these
+types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will
+create descriptors which allow reading and writing the fields by direct
+attribute accesses. These are the
+
+
+.. attribute:: Structure._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 :attr:`_fields_` class variable *after* the class
+ statement that defines the Structure subclass, this allows to create data types
+ that directly or indirectly reference themselves::
+
+ class List(Structure):
+ pass
+ List._fields_ = [("pnext", POINTER(List)),
+ ...
+ ]
+
+ The :attr:`_fields_` class variable must, however, be defined before the type is
+ first used (an instance is created, ``sizeof()`` is called on it, and so on).
+ Later assignments to the :attr:`_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 :attr:`_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 :attr:`_fields_` defined in the sub-subclass,
+ if any.
+
+
+.. attribute:: Structure._pack_
+
+ An optional small integer that allows to override the alignment of structure
+ fields in the instance. :attr:`_pack_` must already be defined when
+ :attr:`_fields_` is assigned, otherwise it will have no effect.
+
+
+.. attribute:: Structure._anonymous_
+
+ An optional sequence that lists the names of unnamed (anonymous) fields.
+ ``_anonymous_`` must be already defined when :attr:`_fields_` is assigned,
+ otherwise it will have no effect.
+
+ The fields listed in this variable must be structure or union type fields.
+ ``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)::
+
+ class _U(Union):
+ _fields_ = [("lptdesc", POINTER(TYPEDESC)),
+ ("lpadesc", POINTER(ARRAYDESC)),
+ ("hreftype", HREFTYPE)]
+
+ class TYPEDESC(Structure):
+ _fields_ = [("u", _U),
+ ("vt", VARTYPE)]
+
+ _anonymous_ = ("u",)
+
+ The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field specifies
+ which one of the union fields is valid. Since the ``u`` field is defined as
+ anonymous field, it is now possible to access the members directly off the
+ TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are equivalent, but the
+ former is faster since it does not need to create a temporary union instance::
+
+ td = TYPEDESC()
+ td.vt = VT_PTR
+ td.lptdesc = POINTER(some_type)
+ td.u.lptdesc = POINTER(some_type)
+
+It is possible to defined sub-subclasses of structures, they inherit the fields
+of the base class. If the subclass definition has a separate :attr:`_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 :attr:`_fields_`. Keyword arguments in the constructor are
+interpreted as attribute assignments, so they will initialize :attr:`_fields_`
+with the same name, or create new attributes for names not present in
+:attr:`_fields_`.
+
+
+.. _ctypes-arrays-pointers:
+
+Arrays and pointers
+^^^^^^^^^^^^^^^^^^^
+
+Not yet written - please see the sections :ref:`ctypes-pointers` and
+section :ref:`ctypes-arrays` in the tutorial.
+