:mod:`!ctypes` --- A foreign function library for Python

========================================================

.. module:: ctypes

:synopsis: A foreign function library for Python.

**Source code:** :source:`Lib/ctypes`

--------------

:mod:`!ctypes` is a foreign function library for Python. It provides C compatible

data types, and allows calling functions in DLLs or shared libraries. It can be

used to wrap these libraries in pure Python.

.. include:: ../includes/optional-module.rst

.. warning::

:mod:`!ctypes` provides low-level access to native libraries and the

process's memory, bypassing Python's safety mechanisms and allowing

execution of arbitrary native code.

Incorrect use can corrupt data and objects, reveal sensitive information,

cause crashes, or otherwise compromise the running process.

.. _ctypes-ctypes-tutorial:

ctypes tutorial

---------------

Note: Some code samples reference the ctypes :class:`c_int` type. On platforms

where ``sizeof(long) == sizeof(int)`` it is an alias to :class:`c_long`.

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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:mod:`!ctypes` exports the :py:data:`~ctypes.cdll`, and on Windows

:py:data:`~ctypes.windll` and :py:data:`~ctypes.oledll`

objects, for loading dynamic link libraries.

You load libraries by accessing them as attributes of these objects.

:py:data:`!cdll` loads libraries which export functions using the

standard ``cdecl`` calling convention, while :py:data:`!windll`

libraries call functions using the ``stdcall``

calling convention.

:py:data:`~oledll` also uses the ``stdcall`` calling convention, and

assumes the functions return a Windows :c:type:`!HRESULT` error code. The error

code is used to automatically raise an :class:`OSError` exception when the

function call fails.

.. versionchanged:: 3.3

Windows errors used to raise :exc:`WindowsError`, which is now an alias

of :exc:`OSError`.

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.

.. note::

Accessing the standard C library through ``cdll.msvcrt`` will use an

outdated version of the library that may be incompatible with the one

being used by Python. Where possible, use native Python functionality,

or else import and use the ``msvcrt`` module.

Other systems require the filename *including* the extension to

load a library, so attribute access can not be used to load libraries. Either the

:meth:`~LibraryLoader.LoadLibrary` method of the dll loaders should be used,

or you should load the library by creating an instance of :py:class:`CDLL`

by calling the constructor.

For example, on Linux::

>>> 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 ...>

>>>

On macOS::

>>> cdll.LoadLibrary("libc.dylib") # doctest: +MACOS

<CDLL 'libc.dylib', handle ... at ...>

>>> libc = CDLL("libc.dylib") # doctest: +MACOS

>>> libc # doctest: +MACOS

<CDLL 'libc.dylib', handle ... at ...>

.. _ctypes-accessing-functions-from-loaded-dlls:

Accessing functions from loaded dlls

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Functions are accessed as attributes of dll objects::

>>> 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 <module>

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

a ``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``

explicitly, and then call it with bytes or string objects respectively.

Sometimes, dlls export functions with names which aren't valid Python

identifiers, like ``"??2@YAPAXI@Z"``. In this case you have to use

:func:`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 <module>

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 ``rand()`` function, which takes no arguments and returns a pseudo-random integer::

>>> print(libc.rand()) # doctest: +SKIP

1804289383

On Windows, you can call the ``GetModuleHandleA()`` function, which returns a win32 module

handle (passing ``None`` as single argument to call it with a ``NULL`` pointer)::

>>> print(hex(windll.kernel32.GetModuleHandleA(None))) # doctest: +WINDOWS

0x1d000000

>>>

:mod:`!ctypes` cannot determine a function's calling convention or signature.

Consult the function's C header file or documentation to choose the correct calling

convention and set the :attr:`~_CFuncPtr.argtypes` attribute, as described in

:ref:`ctypes-specifying-required-argument-types`. Without

:attr:`~_CFuncPtr.argtypes`, the number of arguments is not checked. Calling a

function with an incorrect calling convention or with incorrect arguments can

corrupt memory or crash Python.

On Windows, :mod:`!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 <module>

OSError: exception: access violation reading 0x00000020

>>>

The :mod:`faulthandler` module can help debug crashes,

such as segmentation faults produced by erroneous C library calls.

``None``, integers, bytes objects 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, bytes objects and strings are passed

as pointer to the memory block that contains their data (:c:expr:`char *` or

:c:expr:`wchar_t *`). Python integers are passed as the platform's default C

:c:expr:`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 :mod:`!ctypes` data types.

.. _ctypes-fundamental-data-types:

Fundamental data types

^^^^^^^^^^^^^^^^^^^^^^

:mod:`!ctypes` defines a number of primitive C compatible data types:

.. list-table::

:header-rows: 1

* - ctypes type

- C type

- Python type

- :py:attr:`~_SimpleCData._type_`

* - :class:`c_bool`

- :c:expr:`_Bool`

- :py:class:`bool`

- ``'?'``

* - :class:`c_char`

- :c:expr:`char`

- 1-character :py:class:`bytes`

- ``'c'``

* - :class:`c_wchar`

- :c:type:`wchar_t`

- 1-character :py:class:`str`

- ``'u'``

* - :class:`c_byte`

- :c:expr:`char`

- :py:class:`int`

- ``'b'``

* - :class:`c_ubyte`

- :c:expr:`unsigned char`

- :py:class:`int`

- ``'B'``

* - :class:`c_short`

- :c:expr:`short`

- :py:class:`int`

- ``'h'``

* - :class:`c_ushort`

- :c:expr:`unsigned short`

- :py:class:`int`

- ``'H'``

* - :class:`c_int`

- :c:expr:`int`

- :py:class:`int`

- ``'i'`` \*

* - :class:`c_int8`

- :c:type:`int8_t`

- :py:class:`int`

- \*

* - :class:`c_int16`

- :c:type:`int16_t`

- :py:class:`int`

- \*

* - :class:`c_int32`

- :c:type:`int32_t`

- :py:class:`int`

- \*

* - :class:`c_int64`

- :c:type:`int64_t`

- :py:class:`int`

- \*

* - :class:`c_uint`

- :c:expr:`unsigned int`

- :py:class:`int`

- ``'I'`` \*

* - :class:`c_uint8`

- :c:type:`uint8_t`

- :py:class:`int`

- \*

* - :class:`c_uint16`

- :c:type:`uint16_t`

- :py:class:`int`

- \*

* - :class:`c_uint32`

- :c:type:`uint32_t`

- :py:class:`int`

- \*

* - :class:`c_uint64`

- :c:type:`uint64_t`

- :py:class:`int`

- \*

* - :class:`c_long`

- :c:expr:`long`

- :py:class:`int`

- ``'l'``

* - :class:`c_ulong`

- :c:expr:`unsigned long`

- :py:class:`int`

- ``'L'``

* - :class:`c_longlong`

- :c:expr:`long long`

- :py:class:`int`

- ``'q'`` \*

* - :class:`c_ulonglong`

- :c:expr:`unsigned long long`

- :py:class:`int`

- ``'Q'`` \*

* - :class:`c_size_t`

- :c:type:`size_t`

- :py:class:`int`

- \*

* - :class:`c_ssize_t`

- :c:type:`Py_ssize_t`

- :py:class:`int`

- \*

* - :class:`c_time_t`

- :c:type:`time_t`

- :py:class:`int`

- \*

* - :class:`c_float`

- :c:expr:`float`

- :py:class:`float`

- ``'f'``

* - :class:`c_double`

- :c:expr:`double`

- :py:class:`float`

- ``'d'``

* - :class:`c_longdouble`

- :c:expr:`long double`

- :py:class:`float`

- ``'g'`` \*

* - :class:`c_char_p`

- :c:expr:`char *` (NUL terminated)

- :py:class:`bytes` or ``None``

- ``'z'``

* - :class:`c_wchar_p`

- :c:expr:`wchar_t *` (NUL terminated)

- :py:class:`str` or ``None``

- ``'Z'``

* - :class:`c_void_p`

- :c:expr:`void *`

- :py:class:`int` or ``None``

- ``'P'``

* - :class:`py_object`

- :c:expr:`PyObject *`

- :py:class:`object`

- ``'O'``

* - :ref:`VARIANT_BOOL <ctypes-wintypes>`

- :c:expr:`short int`

- :py:class:`bool`

- ``'v'``

Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is supported

in both C and ``libffi``, the following complex types are available:

.. list-table::

:header-rows: 1

* - ctypes type

- C type

- Python type

- :py:attr:`~_SimpleCData._type_`

* - :class:`c_float_complex`

- :c:expr:`float complex`

- :py:class:`complex`

- ``'Zf'``

* - :class:`c_double_complex`

- :c:expr:`double complex`

- :py:class:`complex`

- ``'Zd'``

* - :class:`c_longdouble_complex`

- :c:expr:`long double complex`

- :py:class:`complex`

- ``'Zg'``

.. versionchanged:: 3.15

The :py:attr:`~_SimpleCData._type_` types ``F``, ``D`` and ``G`` have been

replaced with ``Zf``, ``Zd`` and ``Zg``.

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_wchar_p("Hello, World")

c_wchar_p(140018365411392)

>>> c_ushort(-3)

c_ushort(65533)

>>>

The constructors for numeric types will convert input using

:py:meth:`~object.__bool__`,

:py:meth:`~object.__index__` (for ``int``),

:py:meth:`~object.__float__` or :py:meth:`~object.__complex__`.

This means :py:class:`~ctypes.c_bool` accepts any object with a truth value::

>>> empty_list = []

>>> c_bool(empty_list)

c_bool(False)

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

string objects are immutable)::

>>> s = "Hello, World"

>>> c_s = c_wchar_p(s)

>>> print(c_s)

c_wchar_p(139966785747344)

>>> print(c_s.value)

Hello World

>>> c_s.value = "Hi, there"

>>> print(c_s) # the memory location has changed

c_wchar_p(139966783348904)

>>> print(c_s.value)

Hi, there

>>> print(s) # first object 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

:func:`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 b'\x00\x00\x00'

>>> p = create_string_buffer(b"Hello") # create a buffer containing a NUL terminated string

>>> print(sizeof(p), repr(p.raw))

6 b'Hello\x00'

>>> print(repr(p.value))

b'Hello'

>>> p = create_string_buffer(b"Hello", 10) # create a 10 byte buffer

>>> print(sizeof(p), repr(p.raw))

10 b'Hello\x00\x00\x00\x00\x00'

>>> p.value = b"Hi"

>>> print(sizeof(p), repr(p.raw))

10 b'Hi\x00lo\x00\x00\x00\x00\x00'

>>>

The :func:`create_string_buffer` function replaces the old :func:`!c_buffer`

function (which is still available as an alias). To create a mutable memory

block containing unicode characters of the C type :c:type:`wchar_t`, use the

:func:`create_unicode_buffer` function.

.. _ctypes-calling-functions-continued:

Calling functions, continued

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Note that printf prints to the real standard output channel, *not* to

:data:`sys.stdout`, so these examples will only work at the console prompt, not

from within *IDLE* or *PythonWin*::

>>> printf = libc.printf

>>> printf(b"Hello, %s\n", b"World!")

Hello, World!

14

>>> printf(b"Hello, %S\n", "World!")

Hello, World!

14

>>> printf(b"%d bottles of beer\n", 42)

42 bottles of beer

19

>>> printf(b"%f bottles of beer\n", 42.5)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert parameter 2

>>>

As has been mentioned before, all Python types except integers, strings, and

bytes objects have to be wrapped in their corresponding :mod:`!ctypes` type, so

that they can be converted to the required C data type::

>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))

An int 1234, a double 3.140000

31

>>>

.. _ctypes-calling-variadic-functions:

Calling variadic functions

^^^^^^^^^^^^^^^^^^^^^^^^^^

On a lot of platforms calling variadic functions through ctypes is exactly the same

as calling functions with a fixed number of parameters. On some platforms, and in

particular ARM64 for Apple Platforms, the calling convention for variadic functions

is different than that for regular functions.

On those platforms it is required to specify the :attr:`~_CFuncPtr.argtypes`

attribute for the regular, non-variadic, function arguments:

.. code-block:: python3

libc.printf.argtypes = [ctypes.c_char_p]

Because specifying the attribute does not inhibit portability it is advised to always

specify :attr:`~_CFuncPtr.argtypes` for all variadic functions.

.. _ctypes-calling-functions-with-own-custom-data-types:

Calling functions with your own custom data types

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can also customize :mod:`!ctypes` argument conversion to allow instances of

your own classes be used as function arguments. :mod:`!ctypes` looks for an

:attr:`!_as_parameter_` attribute and uses this as the function argument. The

attribute must be an integer, string, bytes, a :mod:`!ctypes` instance, or an

object with an :attr:`!_as_parameter_` attribute::

>>> class Bottles:

... def __init__(self, number):

... self._as_parameter_ = number

...

>>> bottles = Bottles(42)

>>> printf(b"%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 :deco:`property` which makes the

attribute available on request.

.. _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:`~_CFuncPtr.argtypes` attribute.

:attr:`~_CFuncPtr.argtypes` must be a sequence of C data types (the :func:`!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(b"String '%s', Int %d, Double %f\n", b"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(b"%d %d %d", 1, 2, 3)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be interpreted as ctypes.c_char_p

>>> printf(b"%s %d %f\n", b"X", 2, 3)

X 2 3.000000

13

>>>

Setting :attr:`~_CFuncPtr.argtypes` also causes :mod:`!ctypes` to raise

:exc:`TypeError` if too few arguments are passed::

>>> printf(b"%s %d %f\n", b"X", 2)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

TypeError: this function takes at least 4 arguments (3 given)

Functions using the ``stdcall`` calling convention require exactly as many

arguments as there are items in :attr:`~_CFuncPtr.argtypes`. Functions using

the ``cdecl`` calling convention accept additional arguments, to support

variadic functions. The declaration must match the function's actual signature;

ctypes cannot verify this.

If you have defined your own classes which you pass to function calls, you have

to implement a :meth:`~_CData.from_param` class method for them to be able to use them

in the :attr:`~_CFuncPtr.argtypes` sequence. The :meth:`~_CData.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, its :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, bytes, a :mod:`!ctypes` instance, or an object with an

:attr:`!_as_parameter_` attribute.

.. _ctypes-return-types:

Return types

^^^^^^^^^^^^

.. testsetup::

from ctypes import CDLL, c_char, c_char_p

from ctypes.util import find_library

libc = CDLL(find_library('c'))

strchr = libc.strchr

By default functions are assumed to return the C :c:expr:`int` type. Other

return types can be specified by setting the :attr:`~_CFuncPtr.restype` attribute of the

function object.

The C prototype of :c:func:`time` is ``time_t time(time_t *)``. Because :c:type:`time_t`

might be of a different type than the default return type :c:expr:`int`, you should

specify the :attr:`!restype` attribute::

>>> libc.time.restype = c_time_t

The argument types can be specified using :attr:`~_CFuncPtr.argtypes`::

>>> libc.time.argtypes = (POINTER(c_time_t),)

To call the function with a ``NULL`` pointer as first argument, use ``None``::

>>> print(libc.time(None)) # doctest: +SKIP

1150640792

Here is a more advanced example, it uses the :func:`!strchr` function, which expects

a string pointer and a char, and returns a pointer to a string::

>>> strchr = libc.strchr

>>> strchr(b"abcdef", ord("d")) # doctest: +SKIP

8059983

>>> strchr.restype = c_char_p # c_char_p is a pointer to a string

>>> strchr(b"abcdef", ord("d"))

b'def'

>>> print(strchr(b"abcdef", ord("x")))

None

>>>

If you want to avoid the :func:`ord("x") <ord>` calls above, you can set the

:attr:`~_CFuncPtr.argtypes` attribute, and the second argument will be converted from a

single character Python bytes object into a C char:

.. doctest::

>>> strchr.restype = c_char_p

>>> strchr.argtypes = [c_char_p, c_char]

>>> strchr(b"abcdef", b"d")

b'def'

>>> strchr(b"abcdef", b"def")

Traceback (most recent call last):

ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray or integer expected

>>> print(strchr(b"abcdef", b"x"))

None

>>> strchr(b"abcdef", b"d")

b'def'

>>>

You can also use a callable Python object (a function or a class for example) as

the :attr:`~_CFuncPtr.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 <module>

File "<stdin>", line 3, in ValidHandle

OSError: [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:`~_CFuncPtr.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*.

:mod:`!ctypes` exports the :func:`byref` function which is used to pass parameters

by reference. The same effect can be achieved with the :func:`pointer` function,

although :func:`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(b'\000' * 32)

>>> print(i.value, f.value, repr(s.value))

0 0.0 b''

>>> libc.sscanf(b"1 3.14 Hello", b"%d %f %s",

... byref(i), byref(f), s)

3

>>> print(i.value, f.value, repr(s.value))

1 3.1400001049 b'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 :mod:`!ctypes` module. Each subclass must

define a :attr:`~Structure._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 :mod:`!ctypes` type like :class:`c_int`, or any other

derived :mod:`!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 <module>

TypeError: too many initializers

>>>

You can, however, build much more complicated structures. A structure 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))

Field :term:`descriptor`\s can be retrieved from the *class*, they are useful

for debugging because they can provide useful information.

See :class:`CField`::

>>> POINT.x

<ctypes.CField 'x' type=c_int, ofs=0, size=4>

>>> POINT.y

<ctypes.CField 'y' type=c_int, ofs=4, size=4>

>>>

.. _ctypes-structureunion-alignment-byte-order:

.. warning::

:mod:`!ctypes` does not support passing unions or structures with bit-fields

to functions by value. While this may work on 32-bit x86, it's not

guaranteed by the library to work in the general case. Unions and

structures with bit-fields should always be passed to functions by pointer.

Structure/union layout, alignment and byte order

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, Structure and Union fields are laid out in the same way the C

compiler does it. It is possible to override this behavior entirely by specifying a

:attr:`~Structure._layout_` class attribute in the subclass definition; see

the attribute documentation for details.

It is possible to specify the maximum alignment for the fields and/or for the

structure itself by setting the class attributes :attr:`~Structure._pack_`

and/or :attr:`~Structure._align_`, respectively.

See the attribute documentation for details.

:mod:`!ctypes` uses the native byte order for Structures and Unions. To build

structures with non-native byte order, you can use one of the

:class:`BigEndianStructure`, :class:`LittleEndianStructure`,

:class:`BigEndianUnion`, and :class:`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:`~Structure._fields_` tuples::

>>> class Int(Structure):

... _fields_ = [("first_16", c_int, 16),

... ("second_16", c_int, 16)]

...

>>> print(Int.first_16)

<ctypes.CField 'first_16' type=c_int, ofs=0, bit_size=16, bit_offset=0>

>>> print(Int.second_16)

<ctypes.CField 'second_16' type=c_int, ofs=0, bit_size=16, bit_offset=16>

It is important to note that bit field allocation and layout in memory are not

defined as a C standard; their implementation is compiler-specific.

By default, Python will attempt to match the behavior of a "native" compiler

for the current platform.

See the :attr:`~Structure._layout_` attribute for details on the default

behavior and how to change it.

.. _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 a somewhat artificial 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, end=" ")

...

1 2 3 4 5 6 7 8 9 10

>>>

.. _ctypes-pointers:

Pointers

^^^^^^^^

Pointer instances are created by calling the :func:`pointer` function on a

:mod:`!ctypes` type::

>>> from ctypes import *

>>> i = c_int(42)

>>> pi = pointer(i)

>>>

Pointer instances have a :attr:`~_Pointer.contents` attribute which

returns the object to which the pointer points, the ``i`` object above::

>>> pi.contents

c_long(42)

>>>

Note that :mod:`!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)

>>>

.. XXX Document dereferencing pointers, and that it is preferred over the

.contents attribute.

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.

.. warning::

Because pointer objects support subscription, they implicitly support

:term:`iteration <iterator>`. Unless doing this in a controlled manner,

such as by manually calling :func:`next` on a :func:`pointer` iterator, this

will typically lead to infinite loops or crashes, because ctypes has no way

of knowing when to stop iteration. In other words, a ``pointer`` iterator

will infinitely yield arbitrary memory.

Behind the scenes, the :func:`pointer` function does more than simply create

pointer instances, it has to create pointer *types* first. This is done with the

:func:`POINTER` function, which accepts any :mod:`!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 <module>

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

>>>

:mod:`!ctypes` checks for ``NULL`` when dereferencing pointers (but dereferencing

invalid non-\ ``NULL`` pointers would crash Python)::

>>> null_ptr[0]

Traceback (most recent call last):

....