path: root/sandbox/docpy-writer/input/reference.txt

ctypes manual
+++++++++++++


Shared Libraries, DLLs
----------------------

Shared libraries are accessed when compiling/linking a program, and
when the program is run. The purpose of the ``find`` method 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 ``load`` acts like when a program is run, and
uses the runtime loader directly. ``load_version`` works like ``load``
but tries to be platform independent (for cases where this makes
sense). Loading via attribute access is a shorthand notation
especially usefull for interactive use, it is equivalent to calling
``load_version`` with no version specified.


class LibraryLoader
...................

Instances of ``LibraryLoader`` are used to load shared libraries.
Usually there is no need to create a libraryloader, instead one of the
predefined loaders should be used.

Libraryloaders have the following methods:

find(name, mode=None) : funcdesc
    Try to find a library, load and return it.  ``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 ``-l``).

    ``mode`` allows to override the default flags passed to the
    ``dlopen()`` function, ignored on Windows.

    On Windows, this method does exactly the same as the ``load``
    method.

    On other platforms, this function might call other programs like
    the compiler to find the library.  When using ctypes to write a
    shared library wrapping, consider using ``load_version`` or
    ``load`` instead.

load_version(name, version=None, mode=None) : funcdesc
    Build a system dependent filename from ``name`` and optionally
    ``version``, then load and return it.  ``name`` is the library
    name without any prefix like ``lib`` and suffix like ``.so`` or
    ``.dylib``.  This method should be used if a library is available
    on different platforms, using the particular naming convention of
    each platform.

    ``mode`` allows to override the default flags passed to the
    ``dlopen()`` function, ignored on Windows.

    Example: calling ``loader.load_version('z', '1.1.3')`` would
    possibly load ``/usr/lib/libz.1.1.3.dylib`` on Mac OS X, or
    ``/lib/libz.so.1.1.3`` on a Linux system.

load(libname, mode=None) : funcdesc
    Load and return the library with the given libname.  On most
    systems ``libname`` is the filename of the shared library; when
    it's not a pathname it will be searched in a system dependent list
    of locations (on many systems additional search paths can be
    specified by an environment variable).  Sometimes the file
    extension (like ``.dll`` on Windows) can be omitted.

    ``mode`` allows to override the default flags passed to the
    ``dlopen()`` function.  ``RTLD_LOCAL`` and ``RTLD_GLOBAL`` are
    typical values.  On Windows, ``mode`` is ignored.

load_library(pathname, mode=None) : funcdesc
    Load and return the library with the given pathname.  This method
    passes the ``pathname`` directly to the underlying ``dlopen`` or
    ``LoadLibrary`` function.

    ``mode`` allows to override the default flags passed to the
    ``dlopen()`` function.  ``RTLD_LOCAL`` and ``RTLD_GLOBAL`` are
    typical values.  On Windows, ``mode`` is ignored.

LoadLibrary(pathname, mode=None) : funcdesc
    This is an alias for the ``load_library`` method documented above,
    maintained for backwards comatibility only.


Libaries can also be loaded by accessing them as attributes of the
loader instance, internally this calls ``load_version`` without
specifying ``version`` or ``mode``.  Obviously this only works for
libraries with names that are valid Python identifiers, and when the
name does not start with a ``_`` character.

Predefined library loaders
..........................

ctypes provides some LibraryLoader instances, the differences between
them are the calling conventions the functions will use and the
default return type of the functions.  All these loaders use the
``RTLD_LOCAL`` mode flag.

Functions can be accessed as named attributes of loaded libraries.

On Windows, structured exception handling is used around the function
call to protect Python from crashing in case you pass invalid
parameters to the function.

``cdll``

    Functions provided by libraries loaded using the ``cdll`` loader
    will be called with the standard C calling convention, and have a
    default return type of ``int``.  ctypes releases the Python global
    interpreter lock (GIL) just before calling the foreign function,
    and reacquires it before returing, so other threads are able to
    run.

``windll``

    Windows only.  Functions provided by libraries loaded by
    ``windll`` will be called using the Windows ``__stdcall`` calling
    convention.  ctypes can detect when the wrong number
    of parameters has been passed to the function call by examining
    the stack pointer before and after the function call.  If the
    wrong parameter count was used, an exception is raised (although
    the function really *has* been called).  The return value of the
    function is lost in this case.  Again, the GIL is released during
    the duration of the function call.

``oledll``

    Windows only.  ``oledll`` behaves in the same way as ``windll``,
    except that the called function is expected to return a
    ``HRESULT`` value.  These are long values containing error or
    success codes.  In case the function returns an error ``HRESULT``
    value, a ``WindowsError`` is raised.  The GIL is released during the
    duration of function call.

``pydll``

    This loader allows to call functions in libraries using the
    *Python* calling convention, for example Python C API functions.
    The GIL is *not* released during the function call, and the state
    of the Python error flag is examined after the function returns.
    If the error flag is set, the Python exception is raised.

    ctypes provides a prefabricated instance of ``pydll`` exposing the
    Python C api as the ``pythonapi`` symbol, you should however make
    sure to set the correct ``restype`` for the functions you use.

Library objects
...............

The library loaders create instances of ``CDLL``, ``WinDLL``,
``OleDLL``, or ``PyDLL`` classes.  You can, however, also load a
library by constructing one of these classes by calling the
constructor with the pathname of the library and an optional ``mode``
argument as described in the previous section.

Library objects implement ``__getattr__`` and ``__getitem__`` methods
that allow to access foreign functions by attribute access or
indexing.  The latter is useful if the name of the function is not a
valid Python identifier, or clashes with special Python method names
that start and end with two underscore characters.

Library objects have two private attributes: ``_name`` is the pathname
of the library, ``_handle`` is the handle to the library that
``dlopen`` has returned.


Foreign functions
-----------------

Functions exported from loaded shared libraries (foreign functions)
can be accessed in two ways. The easiest way is to retrieve them as
attributes of library objects by name::

    libc = cdll.find("c") # posix
    libc = cdll.msvcrt # windows
    # attribute access
    atoi = libc.atoi
    # alternative indexing notation
    atoi = libc["atoi"]

This creates an instance of a foreign function object, using the
calling convention specified by the library object ``cdll``, bound to
the C library ``atoi`` function.  The C function is assumed to return
an integer (which is correct for ``atoi``), and the argument types are
not specified (``atoi`` expects a single ``char *`` argument).

If the library function returns a type different from ``int``, the
``restype`` attribute can be set to a ctypes type that describes the
return type, or to ``None`` meaning no return value (``void``).

The optional ``argtypes`` attribute can be set to a sequence of ctypes
types that the function expects.

If needed, the function can (as in C) be called with more arguments
than the length of the argtypes sequence.

The optional ``errcheck`` attribute can be set to a Python callable,
which can be used to validate and/or process the library function's return
value.  ``errcheck`` will be called with three arguments, after the
library function has returned::

    errcheck(retval, function, arguments)

``retval`` is the value that the library function returned, converted
according to ``restype``.  ``function`` is the ctypes function object
(libc.atoi in this case), and ``arguments`` is a tuple containing the
arguments that have been used to call ``function``.  ``errcheck``
should validate the library function result, raise an error if it
detects a failure, or return the needed return value otherwise.

Function prototypes
...................

Another way to access a function exported from shared libraries is to
first create a prototype by calling a factory function, specifying the
return type and the argument types.  The factory function itself
specifies the calling convention: ``CFUNCTYPE`` uses the standard C
calling convention, ``WINFUNCTYPE`` (Windows only) uses the stdcall
calling convention.  The factory function must be called with the
return type plus the argument types.  For the C ``atoi`` function one
would use ``CFUNCTYPE(c_int, c_char_p)``.

This returns a function prototype, which is a ctypes type representing
all functions that are compatible with the calling convention, return
type, and argument types.

The ``CFUNCTYPE`` and ``WINFUNCTYPE`` factory functions cache and
reuse the types they create in internal caches, so is is cheap to call
them over and over with the same or different arguments.

An instance of this function prototype, bound to a foreign library
function, can be created by calling the prototype with the name of the
function as string, and a loaded library::

    proto = CFUNCTYPE(c_int, c_char_p)
    atoi = proto("atoi", libc)

Parameter flags
...............

It is possible to specify a third argument ``paramflags`` when calling
the prototype.  This is used to specify additional information for
each argument: direction of data transfer, the name, and a default
value.

A tuple with the same length as ``argtypes`` (the second argument in
the prototype call) must be used.  Each item in this tuple must be a
tuple, having either one, two, or three items.

The first item is the direction flag, an integer specifying if this is
an input (use ``1``) or an output (use ``2``) parameter.  The optional
second item is a string containing the parameter name, the optional
third item is a default value for the parameter.

If parameter names are specified, the function object created can be
called with named arguments in the usual way.  Arguments with default
values do not need to be specified when the function is called.

``out`` parameter types must be pointer types.  When the function
object is called, ctypes will automatically create empty instances of
them, pass them to the library function, retrieve the value from them,
and return the value, if there is exactly one ``out`` parameter, or a
tuple of values, if there is more than one ``out`` parameter.  The
original foreign function return value is lost in this case (but see
below for how it can be retrieved).

If ``paramflags`` have been used in the prototype call, and an
``errcheck`` attribute is also present, the ``errcheck`` callable will
be called with a fourth parameter ``outargs``::

    errcheck(retval, function, arguments, outargs)

``outargs`` is a tuple containing all the ``out`` parameters that
ctypes has created.  Without the ``errcheck`` function ctypes would
retrieve the values contained in these pointer objects, and return
them.  The ``errcheck`` function can let ctypes continue this
processing by returning the ``outargs`` tuple.  It could also return
something else, or raise an error if it detects that the library
function has failed.

Callback functions
..................

ctypes is able to create C callable functions from Python callables.
This is useful because sometimes library functions need a callback
function parameter; the ``qsort`` C function is such an example.

Callback functions are created by first creating a function prototype
with a call to ``CFUNCTYPE`` or ``WINFUNCTYPE``, specifying the return
type and the argument types that the callback function will receive.

Calling the prototype with a single Python callable will create and
return a C-callable function pointer or callback function.  Note that
this allows using prototypes as decorators creating callback
functions (Windows example)::

    @WINFUNCTYPE(BOOL, HWND, LPARAM)
    def enumwindowsproc(hwnd, lParam):
        ....
        return True

When a Python exception is raised in the Python callable, the return
value of the C callable function is undefined.

Important note: You must keep a reference to the callback AS LONG as
foreign code will call it!  Segfaults will result if the callback is
cleaned up by Python's garbage collector and external code then
tries to call it.

Callback objects can also be called from Python - this may be useful
for debugging.


COM methods (Windows only)
..........................

XXX Should this be left undocumented?  Mentioned for completeness.

The prototypes created by ``WINFUNCTYPE`` can be called with a
positive small integer ``index``, a string ``name``, an optional
``paramflags`` tuple, and a optional ``iid`` parameter.

This creates a function object wrapping a COM method.  ``index`` is
the index into the COM object's virtual function table, ``name`` is
the name of the COM method (only useful for debugging), ``paramflags``
has the same meaning as for normal function objects, and ``iid`` is a
string or buffer containing the interface id of the COM interface
this method belongs to.  ``iid`` is used to get extended COM error
information in case the method returns a FAILED ''HRESULT`` value.

Note that COM methods expect an additional first argument that is NOT
listed in the prototypes ``argtypes`` when they are called: this must
be the integer address of a COM interface pointer.


Simple types
------------

Simple types have some special behaviour: When they are accessed as
structure or union fields, items of array instances, or as foreign
function return values, they are transparently converted from and to
the native Python types int, long, string, and unicode.

This is *not* the case for subclasses of simple data types, so while a
``c_void_p`` type is transparently converted from and to Python
integer or long, a subclass of c_void_p is *not* converted.  This
allows you to define new behaviour almost completely.

Class attributes of simple types
................................

``__ctype__be__``, ``__ctype_le__``

    If the type supports different byte order (pointer types do NOT
    support this), ``__ctype_be__`` and ``__ctype_le__`` are types
    with bug endian and little endian byte order.  For example,
    ``c_int.__ctype_be__`` is an integer type with the memory block in
    big endian byte order.

``_type_``

    Implementation artifact: the typecode for this type, a single
    character string code compatible to what the ``struct`` module uses.
    Additional characters are used for types that the ``struct`` module
    does not support.


Class methods of simple types
.............................

(To be exact, these are not class methods, instead these are methods
of the metaclass.  The most prominent difference to classmethods is
that you can call these methods on the class, but not on the instance
of the simple type.)

``__ctypes_from_outparam__``

    TBD

``from_address``

    TBD

``from_param``

    This class method is used to adapt function parameters.  If a type
    is specified in a function's argtypes sequence, in a function call
    the ``from_param(arg)`` method will be called with the actual
    argument, and the result will be passed to the foreign function
    call as a parameter.

    ``from_param`` usually returns an internal object that you cannot
    use in Python code - it only makes sense to pass this object to
    foreign functions.

    On one hand, ``from_param`` is a performance optimization - it
    allows you to pass Python integers to function calls expecting a
    ``c_int`` argument type, without having to create a full-featured
    ``c_int`` instance.

    On the other hand, ``from_param`` can adapt other objects to
    parameters.  XXX explain the automatic ``byref`` call for byref
    arguments.

``in_dll``

    TBD

Instance attributes of simple types
...................................

``value``

    Allows to get or set the current value of the object.  For simple
    types, this is always a native Python object like integer, long,
    string, unicode, or None.

``_objects`` (never modify this)

    Implementation artifact: a Python object keeping references to
    other objects which must be kept alive.  Never modify anything on
    the returned object. XXX Should probably not be exposed.

``_b_base_`` (readonly)

    Implementation artifact: the base object owning the memory block
    (if any).

``_b_needsfree_`` (readonly)

    Implementation artifact: does this object have to free its memory
    block on destruction.

``_as_parameter_`` (readonly)

    Implementation artifact (?): how to pass this object as a function
    parameter.


Numeric types
.............

Integer types are ``c_byte``, ``c_short``, ``c_int``, ``c_long``,
``c_longlong`` and their unsigned variants ``c_ubyte``, ``c_ushort``,
``c_uint``, ``c_ulong`` and ``c_ulonglong``, floating point types are
``c_float`` and ``c_double``.

The constructor and the ``from_param`` class method accept a Python
integer for integer types, a Python float for floating point types.

On 32-bit platforms where sizeof(int) == sizeof(long), ``c_int`` is an
alias for ``c_long``, on 64-bit platforms where sizeof(long) ==
sizeof(long long), ``c_long`` is an alias for ``c_longlong``.

Character types
...............

Character types are ``c_char`` and ``c_wchar``, representing the C
``char`` and ``wchar_t`` types.

The constructor and the ``from_param`` class method accept a single
character Python string or unicode string.  Conversion between string
and unicode, if needed, is done according to the ctypes
encoding/decoding rules.


Pointer types
.............

The only simple pointer type is ``c_void_p``, which represents the C
``void *`` data type.  ``c_void_p`` can also be written as
``POINTER(None)``.

The constructor accepts one optional argument, which must be an
integer or long (interpreted as an address), or ``None``.

The ``from_param`` class method accepts everything that could be used
as a pointer.  XXX Should accept objects using the buffer interface as
well.

The ``value`` attribute accepts and returns None or integer.

XXX Shouldn't the constructor accept the same types as from_param?


String types
............

ctypes has the ``c_char_p`` and ``c_wchar_p`` types which represent
const pointers to zero terminated strings in C: ``const char *`` and
``const wchar_t *``.  Since strings and Unicode instances are
immutable, these types should be considered readonly: do not pass them
to functions that write into the buffer.

The constructor accepts one optional argument, which must be a Python
or unicode string, an integer, or ``None``.

The ``from_param`` class method accepts a string or a Unicode string,
as well as ``None``.  Conversion between string and Unicode, if
needed, is done according to the ctypes encoding/decoding rules.

XXX Why does the constructor accept an integer, and from_param doesn't?

Structure and union types
-------------------------

ctypes provides the abstract base classes ``Structure`` and ``Union``
to define structure and union types.  Subclasses must at least define
a ``_fields_`` attribute.

Defining field names and types
..............................

``_fields_`` must be a sequence of tuples.  The first item of each
tuple is a string specifying the name of the structure/union field.
The second item must by a ctypes type.

A descriptor will be created for each field, allowing you to access the
field's contents from instances.  Accessed from the class, the fields
expose readonly ``.offset`` and ``.size`` attributes.  ``offset`` is
the byte-offset of the field from the beginning of the
structure/union, ``size`` is the number of bytes the field contains.

A simple example is a POINT structure containing integer fields named
``x`` and ``y``::

    class Point(Structure):
        _fields_ = [("x", c_int),
                    ("y", c_int)]



Field alignment
...............

Normally fields are aligned in the same way as the host's C compiler
would do it.  This native alignment can be overridden by setting a
``_pack_`` attribute in the type.  It must be a small positive integer
which is the maximum field alignment.

Bit fields
..........

Integer fields support bit sizes.  The bit-size must be specified as
the third item of the ``_fields_`` tuple.  Bit fields are constructed
in the same way the host's C compiler does it.  For bit fields, the
field descriptor's ``.size`` attribute contains the number of bits in
the high word, and the bit offset from the beginning of the structure in
the low word.  XXX is that correct?

Recursive data types
....................

To define recursive types, it is possible to assign the ``_fields_``
value *after* the class statement.  Here is an example of a linked
list data structure, which contains a pointer to itself::

    class Node(Structure):
        pass
    Node._fields_ = [("next", POINTER(Node)),
                     ("value", ...)]

``_fields_`` must be set, and cannot be changed, after the type is
used for the first time.

Byte order
..........

It is possible to create Structure and Union types using non-native
byte order by using the ``BigEndianStructure``,
``LittleEndianStructure``, ``BigEndianUnion``, and
``LittleEndianUnion`` base classes.  Structures and Unions with
non-native byte order do *not* support pointer fields.


Builtin functions
-----------------

``addressof(object)``

    Returns the address of a ctypes instance as an integer.

``alignment(type_or_object)``

    Returns the alignment requirements in bytes of a ctypes type or
    instance.

``byref(object)``

    Returns a light-weight pointer to a ctypes instance.  The returned
    object can only be used as function call parameter.  Behaves the
    same as calling ``pointer(object)``, but is a lot faster.  Same as
    ``&object`` in C.

``cast(object, typ)``

    This function is similar to the cast operator in C.  Returns a new
    instance of ``type`` which shares the memory block of ``object``.
    ``typ`` must be a pointer type.

``CFUNCTYPE(restype, *argtypes)``

    Create a function prototype using the C calling convention.


``create_string_buffer(init, size=None)``

    Convenience function to create a mutable character buffer.

    ``init`` must be a string.  If ``size`` is supplied it must be a
    positive integer that specifies the size of the buffer, otherwise
    the length of the ``init`` string is used.
    This function returns a ctypes array of characters ``c_char``.

``create_unicode_buffer(init, size=None)``

    Convenience function to create a mutable unicode buffer.

    ``init`` must be a unicode string.  If ``size`` is supplied it
    must be a positive integer that specifies the number of characters
    in the buffer, otherwise the length of the ``init`` string is
    used.  This function returns a ctypes array of characters ``c_wchar``.


``DllCanUnloadNow()``, ``DllGetClassObject(rclsid, riid, ppv)`` (Windows only)

    Functions used to implement COM servers.


``FormatError([code])`` (Windows only)

    Returns a textual description of the error code, or the last error
    code set by Windows.

``GetLastError()`` (Windows only)

    Returns the last error code set by Windows.

``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 anything else that can be converted into a pointer.

``memset(dst, c, count)``

    Same as the standard C ``memset`` 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.


``pointer(object)``

    This function creates a new pointer instance, pointing to the
    supplied argument which must be an instance of a ctypes type.  The
    return pointer is of type ``POINTER(type(object))``.  If you have
    a ctypes instance, and you want to pass the address of it to a
    function call, you should use ``byref(object)`` instead which is
    much faster.

    NULL pointer instances are boolean``False``, so to check for a
    NULL pointer do this::

        # assuming ptr is in ctypes pointer instance
        if ptr:
            print "Non-NULL pointer instance"
        else:
            print "NULL pointer instance"
    

``POINTER(cls)``

    This factory function creates and returns a new ctypes type.
    Pointer types are cached, so calling this function is cheap.

    To create a ``NULL`` pointer instance, call the created type
    without an argument::

        null_ptr = POINTER(c_int)()


``set_conversion_mode(encoding, errors)``

    This function sets the encoding/decoding rules which are used when
    ctypes has to convert between unicode and byte strings.  It
    returns the previous encoding, as well as a tuple of any errors.
    If not set, default conversions are used:
    On Windows, ``msbc, ignore`` , on other systems, ``ascii, strict``.


``sizeof(type_or_object)``

    Returns the size in bytes of a ctypes type or instance memory
    buffer.  Does the same as the C sizeof() function.


``string_at(addr[, size])``

    This function does the same as the Python ``PyString_FromString`` /
    ``PyString_FromStringAndSize`` C api functions.

``WinError(code=None, descr=None)``

    XXX This is probably the worst named thing in ctypes!

    This function creates a ``WindowsError`` instance.  If ``code`` is
    not specified, GetLastError() is called to determine the error
    code.  If ``descr`` is not specified, ``FormatError`` is called to
    get a textual description of the error.

``WINFUNCTYPE(restype, *argtypes)`` (Windows only)

    Create a function prototype using the __stdcall calling convention
    (on Windows), or using the C calling convention (on Windows CE).

``wstring_at(addr[, size])``

    This function does the same as the Python ``PyUnicode_FromWideString``
    C api function.  If ``size`` is not specified, ``wcslen`` is used
    to determine the string length.


Deprecated functions
....................

These deprecated functions are still supported for backwards
comatibility, they should not be used for new code:

``c_buffer(init, size=None)``

    Deprecated.  Use ``create_string_buffer()`` instead.

``ARRAY(cls, len)``

    Deprecated.  Use ``cls * len`` instead.

``SetPointerType(pointer_class, cls)``

    Deprecated.