| .. 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 |
n | data types, and allows to call functions in dlls/shared libraries. It can be |
n | data types, and allows calling functions in DLLs or shared libraries. It can be |
| used to wrap these libraries in pure Python. |
| |
| |
| .. _ctypes-ctypes-tutorial: |
| |
| ctypes tutorial |
| --------------- |
| |
n | Note: The code samples in this tutorial uses ``doctest`` to make sure that they |
n | 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. |
| |
n | Note: Quite some code samples references the ctypes :class:`c_int` type. This |
n | Note: Some code samples reference the ctypes :class:`c_int` type. This type is |
| type is an alias to the :class:`c_long` type on 32-bit systems. So, you should |
| an alias for the :class:`c_long` type on 32-bit systems. So, you should not be |
| not be confused if :class:`c_long` is printed if you would expect :class:`c_int` |
| confused if :class:`c_long` is printed if you would expect :class:`c_int` --- |
| - they are actually the same type. |
| they are actually the same type. |
| |
| |
| .. _ctypes-loading-dynamic-link-libraries: |
| |
| Loading dynamic link libraries |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
n | ``ctypes`` exports the *cdll*, and on Windows also *windll* and *oledll* objects |
n | ``ctypes`` exports the *cdll*, and on Windows *windll* and *oledll* |
| to load dynamic link libraries. |
| objects, for loading 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 |
n | code is used to automatically raise :class:`WindowsError` Python exceptions when |
n | code is used to automatically raise a :class:`WindowsError` exception when |
| the function call fails. |
| |
n | Here are some examples for Windows, note that ``msvcrt`` is the MS standard C |
n | 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 |
| >>> |
| |
n | Windows appends the usual '.dll' file suffix automatically. |
n | Windows appends the usual ``.dll`` file suffix automatically. |
| |
| On Linux, it is required to specify the filename *including* the extension to |
n | load a library, so attribute access does not work. Either the |
n | load a library, so attribute access can not be used to load libraries. 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 ...> |
| >>> |
| |
n | .. % XXX Add section for Mac OS X. |
n | .. 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:: |
| 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)) |
| |
n | Fields descriptors can be retrieved from the *class*, they are useful for |
n | Field :term:`descriptor`\s can be retrieved from the *class*, they are useful |
| debugging because they can provide useful information:: |
| 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 |
n | compiler does it. It is possible to override this behaviour be specifying a |
n | compiler does it. It is possible to override this behavior 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. |
| 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 |
n | happended? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above:: |
n | happened? 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. |
| |
n | Keep in mind that retrieving subobjects from Structure, Unions, and Arrays |
n | Keep in mind that retrieving sub-objects from Structure, Unions, and Arrays |
| doesn't *copy* the subobject, instead it retrieves a wrapper object accessing |
| doesn't *copy* the sub-object, 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 |
n | block plus some descriptors accessing the contents of the memory. Storing a |
n | block plus some :term:`descriptor`\s accessing the contents of the memory. |
| Python object in the memory block does not store the object itself, instead the |
| Storing a Python object in the memory block does not store the object itself, |
| ``contents`` of the object is stored. Accessing the contents again constructs a |
| instead the ``contents`` of the object is stored. Accessing the contents again |
| new Python each time! |
| constructs a new Python object each time! |
| |
| |
| .. _ctypes-variable-sized-data-types: |
| |
| Variable-sized data types |
| ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| ``ctypes`` provides some support for variable-sized arrays and structures (this |
| |
| 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: |
| |
| |
n | .. class:: CDLL(name, mode=DEFAULT_MODE, handle=None) |
n | .. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False) |
| |
| Instances of this class represent loaded shared libraries. Functions in these |
| libraries use the standard C calling convention, and are assumed to return |
| ``int``. |
| |
| |
n | .. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None) |
n | .. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False) |
| |
| 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. |
| |
| |
n | .. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None) |
n | .. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False) |
| |
| 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. |
| |
n | The Python GIL is released before calling any function exported by these |
n | The Python :term:`global interpreter lock` is released before calling any |
| libraries, and reaquired afterwards. |
| function exported by these libraries, and reacquired 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 |
n | an already loaded shard library, it can be passed as the ``handle`` named |
n | an already loaded shared 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. |
| |
n | The *use_errno* parameter, when set to True, enables a ctypes mechanism that |
| allows to access the system :data:`errno` error number in a safe way. |
| :mod:`ctypes` maintains a thread-local copy of the systems :data:`errno` |
| variable; if you call foreign functions created with ``use_errno=True`` then the |
| :data:`errno` value before the function call is swapped with the ctypes private |
| copy, the same happens immediately after the function call. |
| |
| The function :func:`ctypes.get_errno` returns the value of the ctypes private |
| copy, and the function :func:`ctypes.set_errno` changes the ctypes private copy |
| to a new value and returns the former value. |
| |
| The *use_last_error* parameter, when set to True, enables the same mechanism for |
| the Windows error code which is managed by the :func:`GetLastError` and |
| :func:`SetLastError` Windows API functions; :func:`ctypes.get_last_error` and |
| :func:`ctypes.set_last_error` are used to request and change the ctypes private |
| copy of the windows error code. |
| |
| .. versionadded:: 2.6 |
| The ``use_last_error`` and ``use_errno`` optional parameters |
| were added. |
| |
| .. 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:: 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__` |
n | and :meth:`__getitem__` have special behaviour: functions exported by the shared |
n | and :meth:`__getitem__` have special behavior: 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 |
| |
n | The name of the library passed in the contructor. |
n | The name of the library passed in the constructor. |
| |
| 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. |
| |
n | :meth:`__getattr__` has special behaviour: It allows to load a shared library by |
n | :meth:`__getattr__` has special behavior: 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. |
| |
| |
n | .. method:: LibraryLoader.LoadLibrary(name) |
n | .. method:: LoadLibrary(name) |
| |
n | Load a shared library into the process and return it. This method always |
n | Load a shared library into the process and return it. This method always |
| returns a new instance of the library. |
| returns a new instance of the library. |
| |
| These prefabricated library loaders are available: |
| |
| |
| .. data:: cdll |
| :noindex: |
| |
| Creates :class:`CDLL` instances. |
| 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. |
| |
n | Instances of foreign functions are also C compatible data types; they represent |
n | Instances of foreign functions are also C compatible data types; they |
| C function pointers. |
| represent C function pointers. |
| |
n | This behaviour can be customized by assigning to special attributes of the |
n | This behavior can be customized by assigning to special attributes of the |
| foreign function object. |
| foreign function object. |
| |
| |
n | .. attribute:: _FuncPtr.restype |
n | .. attribute:: restype |
| |
n | Assign a ctypes type to specify the result type of the foreign function. Use |
n | Assign a ctypes type to specify the result type of the foreign function. |
| ``None`` for ``void`` a function not returning anything. |
| Use ``None`` for ``void`` a function not returning anything. |
| |
n | It is possible to assign a callable Python object that is not a ctypes type, in |
n | It is possible to assign a callable Python object that is not a ctypes |
| this case the function is assumed to return a C ``int``, and the callable will |
| type, in this case the function is assumed to return a C ``int``, and the |
| be called with this integer, allowing to do further processing or error |
| callable will be called with this integer, allowing to do further |
| checking. Using this is deprecated, for more flexible postprocessing or error |
| processing or error checking. Using this is deprecated, for more flexible |
| checking use a ctypes data type as :attr:`restype` and assign a callable to the |
| post processing or error checking use a ctypes data type as |
| :attr:`errcheck` attribute. |
| :attr:`restype` and assign a callable to the :attr:`errcheck` attribute. |
| |
| |
n | .. attribute:: _FuncPtr.argtypes |
n | .. attribute:: argtypes |
| |
n | Assign a tuple of ctypes types to specify the argument types that the function |
n | Assign a tuple of ctypes types to specify the argument types that the |
| accepts. Functions using the ``stdcall`` calling convention can only be called |
| function accepts. Functions using the ``stdcall`` calling convention can |
| with the same number of arguments as the length of this tuple; functions using |
| only be called with the same number of arguments as the length of this |
| the C calling convention accept additional, unspecified arguments as well. |
| tuple; functions using the C calling convention accept additional, |
| unspecified arguments as well. |
| |
n | When a foreign function is called, each actual argument is passed to the |
n | 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 |
| :meth:`from_param` class method of the items in the :attr:`argtypes` |
| method allows to adapt the actual argument to an object that the foreign |
| tuple, this method allows to adapt the actual argument to an object that |
| function accepts. For example, a :class:`c_char_p` item in the :attr:`argtypes` |
| the foreign function accepts. For example, a :class:`c_char_p` item in |
| tuple will convert a unicode string passed as argument into an byte string using |
| the :attr:`argtypes` tuple will convert a unicode string passed as |
| ctypes conversion rules. |
| argument into an byte string using ctypes conversion rules. |
| |
n | New: It is now possible to put items in argtypes which are not ctypes types, but |
n | New: It is now possible to put items in argtypes which are not ctypes |
| each item must have a :meth:`from_param` method which returns a value usable as |
| types, but each item must have a :meth:`from_param` method which returns a |
| argument (integer, string, ctypes instance). This allows to define adapters |
| value usable as argument (integer, string, ctypes instance). This allows |
| that can adapt custom objects as function parameters. |
| to define adapters that can adapt custom objects as function parameters. |
| |
| |
n | .. attribute:: _FuncPtr.errcheck |
n | .. attribute:: errcheck |
| |
n | Assign a Python function or another callable to this attribute. The callable |
n | Assign a Python function or another callable to this attribute. The |
| will be called with three or more arguments: |
| callable will be called with three or more arguments: |
| |
n | |
| .. function:: callable(result, func, arguments) |
| .. function:: callable(result, func, arguments) |
| :noindex: |
| :noindex: |
| |
n | ``result`` is what the foreign function returns, as specified by the |
n | ``result`` is what the foreign function returns, as specified |
| :attr:`restype` attribute. |
| by the :attr:`restype` attribute. |
| |
n | ``func`` is the foreign function object itself, this allows to reuse the same |
n | ``func`` is the foreign function object itself, this allows |
| callable object to check or postprocess the results of several functions. |
| to reuse the same callable object to check or post process |
| the results of several functions. |
| |
n | ``arguments`` is a tuple containing the parameters originally passed to the |
n | ``arguments`` is a tuple containing the parameters originally |
| function call, this allows to specialize the behaviour on the arguments used. |
| passed to the function call, this allows to specialize the |
| behavior on the arguments used. |
| |
n | The object that this function returns will be returned from the foreign function |
n | The object that this function returns will be returned from the |
| call, but it can also check the result value and raise an exception if the |
| foreign function call, but it can also check the result value |
| foreign function call failed. |
| 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. |
| |
| |
| |
| 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. |
| |
| |
n | .. function:: CFUNCTYPE(restype, *argtypes) |
n | .. function:: CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) |
| |
| The returned function prototype creates functions that use the standard C |
n | calling convention. The function will release the GIL during the call. |
n | calling convention. The function will release the GIL during the call. If |
| *use_errno* is set to True, the ctypes private copy of the system |
| :data:`errno` variable is exchanged with the real :data:`errno` value bafore |
| and after the call; *use_last_error* does the same for the Windows error |
| code. |
| |
n | .. versionchanged:: 2.6 |
| The optional *use_errno* and *use_last_error* parameters were added. |
| |
n | .. function:: WINFUNCTYPE(restype, *argtypes) |
n | |
| .. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) |
| |
| Windows only: The returned function prototype creates functions that use the |
n | ``stdcall`` calling convention, except on Windows CE where :func:`WINFUNCTYPE` |
n | ``stdcall`` calling convention, except on Windows CE where |
| is the same as :func:`CFUNCTYPE`. The function will release the GIL during the |
| :func:`WINFUNCTYPE` is the same as :func:`CFUNCTYPE`. The function will |
| call. |
| release the GIL during the call. *use_errno* and *use_last_error* have the |
| same meaning as above. |
| |
| |
| .. 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. |
| |
n | Function prototypes created by the factory functions can be instantiated in |
n | Function prototypes created by these factory functions can be instantiated in |
| different ways, depending on the type and number of the parameters in the call. |
| different ways, depending on the type and number of the parameters in the call: |
| |
| |
n | .. function:: prototype(address) |
n | .. function:: prototype(address) |
| :noindex: |
| :noindex: |
| :module: |
| |
n | Returns a foreign function at the specified address. |
n | Returns a foreign function at the specified address which must be an integer. |
| |
| |
n | .. function:: prototype(callable) |
n | .. function:: prototype(callable) |
| :noindex: |
| :noindex: |
| :module: |
| |
n | Create a C callable function (a callback function) from a Python ``callable``. |
n | Create a C callable function (a callback function) from a Python ``callable``. |
| |
| |
n | .. function:: prototype(func_spec[, paramflags]) |
n | .. function:: prototype(func_spec[, paramflags]) |
| :noindex: |
| :noindex: |
| :module: |
| |
n | Returns a foreign function exported by a shared library. ``func_spec`` must be a |
n | 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 |
| 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 |
| exported function as string, or the ordinal of the exported function as small |
| integer. The second item is the shared library instance. |
| integer. The second item is the shared library instance. |
| |
| |
n | .. function:: prototype(vtbl_index, name[, paramflags[, iid]]) |
n | .. function:: prototype(vtbl_index, name[, paramflags[, iid]]) |
| :noindex: |
| :noindex: |
| :module: |
| |
n | Returns a foreign function that will call a COM method. ``vtbl_index`` is the |
n | 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 |
| index into the virtual function table, a small non-negative integer. *name* is |
| name of the COM method. *iid* is an optional pointer to the interface identifier |
| name of the COM method. *iid* is an optional pointer to the interface identifier |
| which is used in extended error reporting. |
| which is used in extended error reporting. |
| |
n | COM methods use a special calling convention: They require a pointer to the COM |
n | 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 |
| interface as first argument, in addition to those parameters that are specified |
| in the :attr:`argtypes` tuple. |
| in the :attr:`argtypes` tuple. |
| |
n | The optional *paramflags* parameter creates foreign function wrappers with much |
n | The optional *paramflags* parameter creates foreign function wrappers with much |
| more functionality than the features described above. |
| more functionality than the features described above. |
| |
n | *paramflags* must be a tuple of the same length as :attr:`argtypes`. |
n | *paramflags* must be a tuple of the same length as :attr:`argtypes`. |
| |
n | Each item in this tuple contains further information about a parameter, it must |
n | Each item in this tuple contains further information about a parameter, it must |
| be a tuple containing 1, 2, or 3 items. |
| be a tuple containing one, two, or three items. |
| |
n | The first item is an integer containing flags for the parameter: |
n | The first item is an integer containing a combination of direction |
| flags for the parameter: |
| |
n | |
n | 1 |
| .. data:: 1 |
| :noindex: |
| |
| Specifies an input parameter to the function. |
| Specifies an input parameter to the function. |
| |
n | |
n | 2 |
| .. data:: 2 |
| :noindex: |
| |
| Output parameter. The foreign function fills in a value. |
| Output parameter. The foreign function fills in a value. |
| |
n | |
n | 4 |
| .. data:: 4 |
| :noindex: |
| |
| Input parameter which defaults to the integer zero. |
| Input parameter which defaults to the integer zero. |
| |
n | The optional second item is the parameter name as string. If this is specified, |
n | The optional second item is the parameter name as string. If this is specified, |
| the foreign function can be called with named parameters. |
| the foreign function can be called with named parameters. |
| |
n | The optional third item is the default value for this parameter. |
n | 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); |
| |
n | Here is the wrapping with ``ctypes``: |
n | Here is the wrapping with ``ctypes``:: |
| |
n | :: |
| |
| >>> from ctypes import c_int, WINFUNCTYPE, windll |
| >>> from ctypes import c_int, WINFUNCTYPE, windll |
| >>> from ctypes.wintypes import HWND, LPCSTR, UINT |
| >>> from ctypes.wintypes import HWND, LPCSTR, UINT |
| >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, c_uint) |
| >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT) |
| >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) |
| >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) |
| >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags) |
| >>> 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") |
| >>> |
| |
| 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); |
| |
n | Here is the wrapping with ``ctypes``: |
n | Here is the wrapping with ``ctypes``:: |
| |
n | :: |
| |
| >>> from ctypes import POINTER, WINFUNCTYPE, windll |
| >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError |
| >>> from ctypes.wintypes import BOOL, HWND, RECT |
| >>> from ctypes.wintypes import BOOL, HWND, RECT |
| >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) |
| >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) |
| >>> paramflags = (1, "hwnd"), (2, "lprect") |
| >>> paramflags = (1, "hwnd"), (2, "lprect") |
| >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags) |
| >>> 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 |
n | ... |
| >>> 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 |
n | >>> |
n | ... |
| >>> GetWindowRect.errcheck = errcheck |
| >>> |
| |
| |
| .. _ctypes-utility-functions: |
| |
| Utility functions |
| ^^^^^^^^^^^^^^^^^ |
| 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() |
| |
n | Windows only: This function is a hook which allows to implement inprocess COM |
n | Windows only: This function is a hook which allows to implement in-process COM |
| servers with ctypes. It is called from the DllCanUnloadNow function that the |
| _ctypes extension dll exports. |
| |
| |
| .. function:: DllGetClassObject() |
| |
n | Windows only: This function is a hook which allows to implement inprocess COM |
n | Windows only: This function is a hook which allows to implement in-process COM |
| servers with ctypes. It is called from the DllGetClassObject function that the |
| ``_ctypes`` extension dll exports. |
| |
n | .. function:: find_library(name) |
| :module: ctypes.util |
| |
| 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 dependent. |
| |
| .. versionchanged:: 2.6 |
| Windows only: ``find_library("m")`` or |
| ``find_library("c")`` return the result of a call to |
| ``find_msvcrt()``. |
| |
| .. function:: find_msvcrt() |
| :module: ctypes.util |
| |
| Windows only: return the filename of the VC runtype library used |
| by Python, and by the extension modules. If the name of the |
| library cannot be determined, ``None`` is returned. |
| |
| If you need to free memory, for example, allocated by an extension |
| module with a call to the ``free(void *)``, it is important that you |
| use the function in the same library that allocated the memory. |
| |
| .. versionadded:: 2.6 |
| |
| .. 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. |
n | This function calls the Windows `GetLastError()` function directly, |
| it does not return the ctypes-private copy of the error code. |
| |
n | .. function:: get_errno() |
| |
| Returns the current value of the ctypes-private copy of the system |
| :data:`errno` variable in the calling thread. |
| |
| .. versionadded:: 2.6 |
| |
| .. function:: get_last_error() |
| |
| Windows only: returns the current value of the ctypes-private copy of the system |
| :data:`LastError` variable in the calling thread. |
| |
| .. versionadded:: 2.6 |
| |
| .. 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. |
| |
| |
| 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')``. |
| |
| |
n | .. function:: set_errno(value) |
| |
| Set the current value of the ctypes-private copy of the system :data:`errno` |
| variable in the calling thread to *value* and return the previous value. |
| |
| .. versionadded:: 2.6 |
| |
| .. function:: set_last_error(value) |
| |
| Windows only: set the current value of the ctypes-private copy of the system |
| :data:`LastError` variable in the calling thread to *value* and return the |
| previous value. |
| |
| .. versionadded:: 2.6 |
| |
| .. 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]) |
| |
n | This function returns the string starting at memory address address. If size is |
n | This function returns the string starting at memory address address. If size |
| specified, it is used as size, otherwise the string is assumed to be zero- |
| is specified, it is used as size, otherwise the string is assumed to be |
| terminated. |
| 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 |
n | spcified, :func:`FormatError` is called to get a textual description of the |
n | specified, :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 |
n | number of characters of the string, otherwise the string is assumed to be zero- |
n | number of characters of the string, otherwise the string is assumed to be |
| terminated. |
| zero-terminated. |
| |
| |
| .. _ctypes-data-types: |
| |
| Data types |
| ^^^^^^^^^^ |
| |
| |
| |
| 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. |
| |
n | Common methods of ctypes data types, these are all class methods (to be exact, |
n | Common methods of ctypes data types, these are all class methods (to be |
| they are methods of the metaclass): |
| exact, they are methods of the :term:`metaclass`): |
| |
| |
n | .. method:: _CData.from_buffer(source[, offset]) |
| |
| This method returns a ctypes instance that shares the buffer of |
| the ``source`` object. The ``source`` object must support the |
| writeable buffer interface. The optional ``offset`` parameter |
| specifies an offset into the source buffer in bytes; the default |
| is zero. If the source buffer is not large enough a ValueError |
| is raised. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: _CData.from_buffer_copy(source[, offset]) |
| |
| This method creates a ctypes instance, copying the buffer from |
| the source object buffer which must be readable. The optional |
| ``offset`` parameter specifies an offset into the source buffer |
| in bytes; the default is zero. If the source buffer is not |
| large enough a ValueError is raised. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. method:: _CData.from_address(address) |
| .. method:: from_address(address) |
| |
n | This method returns a ctypes type instance using the memory specified by address |
n | This method returns a ctypes type instance using the memory specified by |
| which must be an integer. |
| address which must be an integer. |
| |
| |
n | .. method:: _CData.from_param(obj) |
n | .. method:: from_param(obj) |
| |
n | This method adapts obj to a ctypes type. It is called with the actual object |
n | This method adapts *obj* to a ctypes type. It is called with the actual |
| used in a foreign function call, when the type is present in the foreign |
| object used in a foreign function call when the type is present in the |
| functions :attr:`argtypes` tuple; it must return an object that can be used as |
| foreign function's :attr:`argtypes` tuple; it must return an object that |
| function call parameter. |
| can be used as a function call parameter. |
| |
n | All ctypes data types have a default implementation of this classmethod, |
n | 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 |
| that normally returns ``obj`` if that is an instance of the type. Some |
| accept other objects as well. |
| types accept other objects as well. |
| |
| |
n | .. method:: _CData.in_dll(name, library) |
n | .. method:: in_dll(library, name) |
| |
n | This method returns a ctypes type instance exported by a shared library. *name* |
n | This method returns a ctypes type instance exported by a shared |
| is the name of the symbol that exports the data, ``library`` is the loaded |
| library. *name* is the name of the symbol that exports the data, *library* |
| shared library. |
| is the loaded shared library. |
| |
n | |
| Common instance variables of ctypes data types: |
| Common instance variables of ctypes data types: |
| |
| |
n | .. attribute:: _CData._b_base_ |
n | .. attribute:: _b_base_ |
| |
n | Sometimes ctypes data instances do not own the memory block they contain, |
n | 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 |
| 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 |
| :attr:`_b_base_` read-only member is the root ctypes object that owns the |
| block. |
| memory block. |
| |
| |
n | .. attribute:: _CData._b_needsfree_ |
n | .. attribute:: _b_needsfree_ |
| |
n | This readonly variable is true when the ctypes data instance has allocated the |
n | This read-only variable is true when the ctypes data instance has |
| memory block itself, false otherwise. |
| allocated the memory block itself, false otherwise. |
| |
| |
n | .. attribute:: _CData._objects |
n | .. attribute:: _objects |
| |
n | This member is either ``None`` or a dictionary containing Python objects that |
n | This member is either ``None`` or a dictionary containing Python objects |
| need to be kept alive so that the memory block contents is kept valid. This |
| that need to be kept alive so that the memory block contents is kept |
| object is only exposed for debugging; never modify the contents of this |
| valid. This object is only exposed for debugging; never modify the |
| dictionary. |
| contents of this dictionary. |
| |
| |
n | .. _ctypes-fundamental-data-types: |
n | .. _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. |
| |
n | .. versionchanged:: 2.6 |
| ctypes data types that are not and do not contain pointers can |
| now be pickled. |
| |
| Instances have a single attribute: |
| Instances have a single attribute: |
| |
| |
n | .. attribute:: _SimpleCData.value |
n | .. attribute:: value |
| |
n | This attribute contains the actual value of the instance. For integer and |
n | 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 |
| pointer types, it is an integer, for character types, it is a single |
| string, for character pointer types it is a Python string or unicode string. |
| character string, for character pointer types it is a Python string or |
| unicode string. |
| |
n | When the ``value`` attribute is retrieved from a ctypes instance, usually a new |
n | When the ``value`` attribute is retrieved from a ctypes instance, usually |
| object is returned each time. ``ctypes`` does *not* implement original object |
| a new object is returned each time. ``ctypes`` does *not* implement |
| return, always a new object is constructed. The same is true for all other |
| original object return, always a new object is constructed. The same is |
| ctypes object instances. |
| 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. |
| |
n | Subclasses of fundamental data types do *not* inherit this behaviour. So, if a |
n | Subclasses of fundamental data types do *not* inherit this behavior. 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 |
| 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. |
| |
n | Concrete structure and union types must be created by subclassing one of these |
n | 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 |
| types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will |
| create descriptors which allow reading and writing the fields by direct |
| create :term:`descriptor`\s which allow reading and writing the fields by direct |
| attribute accesses. These are the |
| attribute accesses. These are the |
| |
| |
n | .. attribute:: Structure._fields_ |
n | .. attribute:: _fields_ |
| |
n | A sequence defining the structure fields. The items must be 2-tuples or |
n | 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 |
| 3-tuples. The first item is the name of the field, the second item |
| the type of the field; it can be any ctypes data type. |
| specifies the type of the field; it can be any ctypes data type. |
| |
n | For integer type fields like :class:`c_int`, a third optional item can be given. |
n | For integer type fields like :class:`c_int`, a third optional item can be |
| It must be a small positive integer defining the bit width of the field. |
| given. It must be a small positive integer defining the bit width of the |
| field. |
| |
n | Field names must be unique within one structure or union. This is not checked, |
n | Field names must be unique within one structure or union. This is not |
| only one field can be accessed when names are repeated. |
| checked, only one field can be accessed when names are repeated. |
| |
n | It is possible to define the :attr:`_fields_` class variable *after* the class |
n | It is possible to define the :attr:`_fields_` class variable *after* the |
| statement that defines the Structure subclass, this allows to create data types |
| class statement that defines the Structure subclass, this allows to create |
| that directly or indirectly reference themselves:: |
| data types that directly or indirectly reference themselves:: |
| |
n | class List(Structure): |
n | class List(Structure): |
| pass |
| pass |
| List._fields_ = [("pnext", POINTER(List)), |
| List._fields_ = [("pnext", POINTER(List)), |
| ... |
| ... |
| ] |
| ] |
| |
n | The :attr:`_fields_` class variable must, however, be defined before the type is |
n | The :attr:`_fields_` class variable must, however, be defined before the |
| first used (an instance is created, ``sizeof()`` is called on it, and so on). |
| type is first used (an instance is created, ``sizeof()`` is called on it, |
| Later assignments to the :attr:`_fields_` class variable will raise an |
| and so on). Later assignments to the :attr:`_fields_` class variable will |
| AttributeError. |
| raise an AttributeError. |
| |
n | Structure and union subclass constructors accept both positional and named |
n | Structure and union subclass constructors accept both positional and named |
| arguments. Positional arguments are used to initialize the fields in the same |
| arguments. Positional arguments are used to initialize the fields in the |
| order as they appear in the :attr:`_fields_` definition, named arguments are |
| same order as they appear in the :attr:`_fields_` definition, named |
| used to initialize the fields with the corresponding name. |
| arguments are used to initialize the fields with the corresponding name. |
| |
n | It is possible to defined sub-subclasses of structure types, they inherit the |
n | It is possible to defined sub-subclasses of structure types, they inherit |
| fields of the base class plus the :attr:`_fields_` defined in the sub-subclass, |
| the fields of the base class plus the :attr:`_fields_` defined in the |
| if any. |
| sub-subclass, if any. |
| |
| |
n | .. attribute:: Structure._pack_ |
n | .. attribute:: _pack_ |
| |
n | An optional small integer that allows to override the alignment of structure |
n | An optional small integer that allows to override the alignment of |
| fields in the instance. :attr:`_pack_` must already be defined when |
| structure fields in the instance. :attr:`_pack_` must already be defined |
| :attr:`_fields_` is assigned, otherwise it will have no effect. |
| when :attr:`_fields_` is assigned, otherwise it will have no effect. |
| |
| |
n | .. attribute:: Structure._anonymous_ |
n | .. attribute:: _anonymous_ |
| |
n | An optional sequence that lists the names of unnamed (anonymous) fields. |
n | An optional sequence that lists the names of unnamed (anonymous) fields. |
| ``_anonymous_`` must be already defined when :attr:`_fields_` is assigned, |
| ``_anonymous_`` must be already defined when :attr:`_fields_` is assigned, |
| otherwise it will have no effect. |
| otherwise it will have no effect. |
| |
n | The fields listed in this variable must be structure or union type fields. |
n | 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 |
| ``ctypes`` will create descriptors in the structure type that allows to |
| the nested fields directly, without the need to create the structure or union |
| access the nested fields directly, without the need to create the |
| field. |
| structure or union field. |
| |
n | Here is an example type (Windows):: |
n | Here is an example type (Windows):: |
| |
n | class _U(Union): |
n | class _U(Union): |
| _fields_ = [("lptdesc", POINTER(TYPEDESC)), |
| _fields_ = [("lptdesc", POINTER(TYPEDESC)), |
| ("lpadesc", POINTER(ARRAYDESC)), |
| ("lpadesc", POINTER(ARRAYDESC)), |
| ("hreftype", HREFTYPE)] |
| ("hreftype", HREFTYPE)] |
| |
n | class TYPEDESC(Structure): |
n | class TYPEDESC(Structure): |
| _fields_ = [("u", _U), |
| _fields_ = [("u", _U), |
| ("vt", VARTYPE)] |
| ("vt", VARTYPE)] |
| |
n | _anonymous_ = ("u",) |
n | _anonymous_ = ("u",) |
| |
n | The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field specifies |
n | The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field |
| which one of the union fields is valid. Since the ``u`` field is defined as |
| specifies which one of the union fields is valid. Since the ``u`` field |
| anonymous field, it is now possible to access the members directly off the |
| is defined as anonymous field, it is now possible to access the members |
| TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are equivalent, but the |
| directly off the TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` |
| former is faster since it does not need to create a temporary union instance:: |
| are equivalent, but the former is faster since it does not need to create |
| a temporary union instance:: |
| |
n | td = TYPEDESC() |
n | td = TYPEDESC() |
| td.vt = VT_PTR |
| td.vt = VT_PTR |
| td.lptdesc = POINTER(some_type) |
| td.lptdesc = POINTER(some_type) |
| td.u.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 |