mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-31 10:26:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Merged revisions 77108-77109 via svnmerge from

Browse source 
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r77108 | georg.brandl | 2009-12-29 11:34:34 +0100 (Di, 29 Dez 2009) | 1 line

  #7569: clarification about c_char_p.
........
  r77109 | georg.brandl | 2009-12-29 12:06:31 +0100 (Di, 29 Dez 2009) | 1 line

  Improve markup of ctypes docs.
........
This commit is contained in:
Georg Brandl 2009-12-29 11:24:00 +00:00
parent e61fab36fe
commit 1d837bc998
1 changed files with 235 additions and 229 deletions
Download patch file Download diff file Expand all files Collapse all files

456
Doc/library/ctypes.rst
View file

@ -6,7 +6,7 @@
.. moduleauthor:: Thomas Heller <theller@python.net> .. moduleauthor:: Thomas Heller <theller@python.net>
``ctypes`` is a foreign function library for Python. It provides C compatible :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 data types, and allows calling functions in DLLs or shared libraries. It can be
used to wrap these libraries in pure Python. used to wrap these libraries in pure Python.
@ -16,9 +16,9 @@ used to wrap these libraries in pure Python.
ctypes tutorial ctypes tutorial
--------------- ---------------
Note: The code samples in this tutorial use :mod:`doctest` to make sure that they Note: The code samples in this tutorial use :mod:`doctest` to make sure that
actually work. Since some code samples behave differently under Linux, Windows, they actually work. Since some code samples behave differently under Linux,
or Mac OS X, they contain doctest directives in comments. Windows, or Mac OS X, they contain doctest directives in comments.
Note: Some code samples reference the ctypes :class:`c_int` type. This type is Note: Some code samples reference the ctypes :class:`c_int` type. This type is
an alias for the :class:`c_long` type on 32-bit systems. So, you should not be an alias for the :class:`c_long` type on 32-bit systems. So, you should not be
@ -38,9 +38,9 @@ You load libraries by accessing them as attributes of these objects. *cdll*
loads libraries which export functions using the standard ``cdecl`` calling loads libraries which export functions using the standard ``cdecl`` calling
convention, while *windll* libraries call functions using the ``stdcall`` convention, while *windll* libraries call functions using the ``stdcall``
calling convention. *oledll* also uses the ``stdcall`` calling convention, and calling convention. *oledll* also uses the ``stdcall`` calling convention, and
assumes the functions return a Windows :class:`HRESULT` error code. The error assumes the functions return a Windows :ctype:`HRESULT` error code. The error
code is used to automatically raise a :class:`WindowsError` exception when code is used to automatically raise a :class:`WindowsError` exception when the
the function call fails. function call fails.
Here are some examples for Windows. Note that ``msvcrt`` is the MS standard C 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 library containing most standard C functions, and uses the cdecl calling
@ -109,8 +109,8 @@ version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW``
explicitly, and then call it with bytes or string objects respectively. explicitly, and then call it with bytes or string objects respectively.
Sometimes, dlls export functions with names which aren't valid Python Sometimes, dlls export functions with names which aren't valid Python
identifiers, like ``"??2@YAPAXI@Z"``. In this case you have to use ``getattr`` identifiers, like ``"??2@YAPAXI@Z"``. In this case you have to use
to retrieve the function:: :func:`getattr` to retrieve the function::
>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS >>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS
<_FuncPtr object at 0x...> <_FuncPtr object at 0x...>
@ -149,8 +149,8 @@ as the NULL pointer)::
0x1d000000 0x1d000000
>>> >>>
:mod:`ctypes` tries to protect you from calling functions with the wrong number of :mod:`ctypes` tries to protect you from calling functions with the wrong number
arguments or the wrong calling convention. Unfortunately this only works on of arguments or the wrong calling convention. Unfortunately this only works on
Windows. It does this by examining the stack after the function returns, so Windows. It does this by examining the stack after the function returns, so
although an error is raised the function *has* been called:: although an error is raised the function *has* been called::
@ -192,15 +192,15 @@ argument values::
WindowsError: exception: access violation reading 0x00000020 WindowsError: exception: access violation reading 0x00000020
>>> >>>
There are, however, enough ways to crash Python with :mod:`ctypes`, so you should There are, however, enough ways to crash Python with :mod:`ctypes`, so you
be careful anyway. should be careful anyway.
``None``, integers, bytes objects and (unicode) strings are the only native ``None``, integers, bytes objects and (unicode) strings are the only native
Python objects that can directly be used as parameters in these function calls. 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 ``None`` is passed as a C ``NULL`` pointer, bytes objects and strings are passed
passed as pointer to the memory block that contains their data (``char *`` or as pointer to the memory block that contains their data (:ctype:`char *` or
``wchar_t *``). Python integers are passed as the platforms :ctype:`wchar_t *`). Python integers are passed as the platforms default C
default C ``int`` type, their value is masked to fit into the C type. :ctype:`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 Before we move on calling functions with other parameter types, we have to learn
more about :mod:`ctypes` data types. more about :mod:`ctypes` data types.
@ -213,47 +213,46 @@ Fundamental data types
:mod:`ctypes` defines a number of primitive C compatible data types : :mod:`ctypes` defines a number of primitive C compatible data types :
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| ctypes type | C type | Python type | | ctypes type | C type | Python type |
+======================+================================+============================+ +======================+========================================+============================+
| :class:`c_char` | ``char`` | 1-character bytes object | | :class:`c_char` | :ctype:`char` | 1-character bytes object |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_wchar` | ``wchar_t`` | 1-character string | | :class:`c_wchar` | :ctype:`wchar_t` | 1-character string |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_byte` | ``char`` | int | | :class:`c_byte` | :ctype:`char` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_ubyte` | ``unsigned char`` | int | | :class:`c_ubyte` | :ctype:`unsigned char` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_short` | ``short`` | int | | :class:`c_short` | :ctype:`short` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_ushort` | ``unsigned short`` | int | | :class:`c_ushort` | :ctype:`unsigned short` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_int` | ``int`` | int | | :class:`c_int` | :ctype:`int` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_uint` | ``unsigned int`` | int | | :class:`c_uint` | :ctype:`unsigned int` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_long` | ``long`` | int | | :class:`c_long` | :ctype:`long` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_ulong` | ``unsigned long`` | int | | :class:`c_ulong` | :ctype:`unsigned long` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_longlong` | ``__int64`` or ``long long`` | int | | :class:`c_longlong` | :ctype:`__int64` or :ctype:`long long` | int |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_ulonglong` | ``unsigned __int64`` or | int | | :class:`c_ulonglong` | :ctype:`unsigned __int64` or | int |
| | ``unsigned long long`` | | | | :ctype:`unsigned long long` | |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_float` | ``float`` | float | | :class:`c_float` | :ctype:`float` | float |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_double` | ``double`` | float | | :class:`c_double` | :ctype:`double` | float |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_longdouble`| ``long double`` | float | | :class:`c_longdouble`| :ctype:`long double` | float |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_char_p` | ``char *`` (NUL terminated) | bytes object or ``None`` | | :class:`c_char_p` | :ctype:`char *` (NUL terminated) | bytes object or ``None`` |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_wchar_p` | ``wchar_t *`` (NUL terminated) | string or ``None`` | | :class:`c_wchar_p` | :ctype:`wchar_t *` (NUL terminated) | string or ``None`` |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
| :class:`c_void_p` | ``void *`` | int or ``None`` | | :class:`c_void_p` | :ctype:`void *` | int or ``None`` |
+----------------------+--------------------------------+----------------------------+ +----------------------+----------------------------------------+----------------------------+
All these types can be created by calling them with an optional initializer of All these types can be created by calling them with an optional initializer of
the correct type and value:: the correct type and value::
@ -318,10 +317,10 @@ property::
10 b'Hi\x00lo\x00\x00\x00\x00\x00' 10 b'Hi\x00lo\x00\x00\x00\x00\x00'
>>> >>>
The :func:`create_string_buffer` function replaces the ``c_buffer`` function The :func:`create_string_buffer` function replaces the :func:`c_buffer` function
(which is still available as an alias), as well as the ``c_string`` function (which is still available as an alias), as well as the :func:`c_string` function
from earlier ctypes releases. To create a mutable memory block containing from earlier ctypes releases. To create a mutable memory block containing
unicode characters of the C type ``wchar_t`` use the unicode characters of the C type :ctype:`wchar_t` use the
:func:`create_unicode_buffer` function. :func:`create_unicode_buffer` function.
@ -365,8 +364,8 @@ that they can be converted to the required C data type::
Calling functions with your 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 You can also customize :mod:`ctypes` argument conversion to allow instances of
own classes be used as function arguments. :mod:`ctypes` looks for an your own classes be used as function arguments. :mod:`ctypes` looks for an
:attr:`_as_parameter_` attribute and uses this as the function argument. Of :attr:`_as_parameter_` attribute and uses this as the function argument. Of
course, it must be one of integer, string, or bytes:: course, it must be one of integer, string, or bytes::
@ -432,9 +431,9 @@ integer, string, bytes, a :mod:`ctypes` instance, or an object with an
Return types Return types
^^^^^^^^^^^^ ^^^^^^^^^^^^
By default functions are assumed to return the C ``int`` type. Other return By default functions are assumed to return the C :ctype:`int` type. Other
types can be specified by setting the :attr:`restype` attribute of the function return types can be specified by setting the :attr:`restype` attribute of the
object. function object.
Here is a more advanced example, it uses the ``strchr`` function, which expects Here is a more advanced example, it uses the ``strchr`` function, which expects
a string pointer and a char, and returns a pointer to a string:: a string pointer and a char, and returns a pointer to a string::
@ -469,7 +468,7 @@ single character Python bytes object into a C char::
You can also use a callable Python object (a function or a class for example) as You can also use a callable Python object (a function or a class for example) as
the :attr:`restype` attribute, if the foreign function returns an integer. The the :attr:`restype` attribute, if the foreign function returns an integer. The
callable will be called with the ``integer`` the C function returns, and the 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 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:: useful to check for error return values and automatically raise an exception::
@ -563,8 +562,8 @@ Here is a simple example of a POINT structure, which contains two integers named
You can, however, build much more complicated structures. Structures can itself You can, however, build much more complicated structures. Structures can itself
contain other structures by using a structure as a field type. contain other structures by using a structure as a field type.
Here is a RECT structure which contains two POINTs named ``upperleft`` and Here is a RECT structure which contains two POINTs named *upperleft* and
``lowerright`` :: *lowerright*::
>>> class RECT(Structure): >>> class RECT(Structure):
... _fields_ = [("upperleft", POINT), ... _fields_ = [("upperleft", POINT),
@ -605,8 +604,9 @@ what ``#pragma pack(n)`` also does in MSVC.
:mod:`ctypes` uses the native byte order for Structures and Unions. To build :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 structures with non-native byte order, you can use one of the
BigEndianStructure, LittleEndianStructure, BigEndianUnion, and LittleEndianUnion :class:`BigEndianStructure`, :class:`LittleEndianStructure`,
base classes. These classes cannot contain pointer fields. :class:`BigEndianUnion`, and :class:`LittleEndianUnion` base classes. These
classes cannot contain pointer fields.
.. _ctypes-bit-fields-in-structures-unions: .. _ctypes-bit-fields-in-structures-unions:
@ -692,7 +692,7 @@ Pointer instances are created by calling the :func:`pointer` function on a
>>> pi = pointer(i) >>> pi = pointer(i)
>>> >>>
Pointer instances have a ``contents`` attribute which returns the object to Pointer instances have a :attr:`contents` attribute which returns the object to
which the pointer points, the ``i`` object above:: which the pointer points, the ``i`` object above::
>>> pi.contents >>> pi.contents
@ -717,7 +717,8 @@ would cause the pointer to point to the memory location where this is stored::
c_long(99) c_long(99)
>>> >>>
.. XXX Document dereferencing pointers, and that it is preferred over the .contents attribute. .. XXX Document dereferencing pointers, and that it is preferred over the
.contents attribute.
Pointer instances can also be indexed with integers:: Pointer instances can also be indexed with integers::
@ -1280,9 +1281,9 @@ the library to load.
The exact functionality is system dependent. The exact functionality is system dependent.
On Linux, :func:`find_library` tries to run external programs (/sbin/ldconfig, On Linux, :func:`find_library` tries to run external programs
gcc, and objdump) to find the library file. It returns the filename of the (``/sbin/ldconfig``, ``gcc``, and ``objdump``) to find the library file. It
library file. Here are some examples:: returns the filename of the library file. Here are some examples::
>>> from ctypes.util import find_library >>> from ctypes.util import find_library
>>> find_library("m") >>> find_library("m")
@ -1329,7 +1330,7 @@ way is to instantiate one of the following classes:
Instances of this class represent loaded shared libraries. Functions in these Instances of this class represent loaded shared libraries. Functions in these
libraries use the standard C calling convention, and are assumed to return libraries use the standard C calling convention, and are assumed to return
``int``. :ctype:`int`.
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False) .. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
@ -1346,7 +1347,7 @@ way is to instantiate one of the following classes:
Windows only: Instances of this class represent loaded shared libraries, Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are functions in these libraries use the ``stdcall`` calling convention, and are
assumed to return ``int`` by default. assumed to return :ctype:`int` by default.
On Windows CE only the standard calling convention is used, for convenience the 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 :class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this
@ -1368,12 +1369,13 @@ function exported by these libraries, and reacquired afterwards.
All these classes can be instantiated by calling them with at least one 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 argument, the pathname of the shared library. If you have an existing handle to
an already loaded shared library, it can be passed as the ``handle`` named an already loaded shared library, it can be passed as the ``handle`` named
parameter, otherwise the underlying platforms ``dlopen`` or :meth:`LoadLibrary` parameter, otherwise the underlying platforms ``dlopen`` or ``LoadLibrary``
function is used to load the library into the process, and to get a handle to function is used to load the library into the process, and to get a handle to
it. it.
The *mode* parameter can be used to specify how the library is loaded. For The *mode* parameter can be used to specify how the library is loaded. For
details, consult the :manpage:`dlopen(3)` manpage, on Windows, *mode* is ignored. details, consult the :manpage:`dlopen(3)` manpage, on Windows, *mode* is
ignored.
The *use_errno* parameter, when set to True, enables a ctypes mechanism that 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. allows to access the system :data:`errno` error number in a safe way.
@ -1439,7 +1441,7 @@ loader instance.
.. class:: LibraryLoader(dlltype) .. class:: LibraryLoader(dlltype)
Class which loads shared libraries. ``dlltype`` should be one of the Class which loads shared libraries. *dlltype* should be one of the
:class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types. :class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types.
:meth:`__getattr__` has special behavior: It allows to load a shared library by :meth:`__getattr__` has special behavior: It allows to load a shared library by
@ -1484,10 +1486,10 @@ object is available:
.. data:: pythonapi .. data:: pythonapi
:noindex: :noindex:
An instance of :class:`PyDLL` that exposes Python C api functions as attributes. An instance of :class:`PyDLL` that exposes Python C API functions as
Note that all these functions are assumed to return C ``int``, which is of attributes. Note that all these functions are assumed to return C
course not always the truth, so you have to assign the correct :attr:`restype` :ctype:`int`, which is of course not always the truth, so you have to assign
attribute to use these functions. the correct :attr:`restype` attribute to use these functions.
.. _ctypes-foreign-functions: .. _ctypes-foreign-functions:
@ -1515,11 +1517,11 @@ They are instances of a private class:
.. attribute:: restype .. attribute:: restype
Assign a ctypes type to specify the result type of the foreign function. Assign a ctypes type to specify the result type of the foreign function.
Use ``None`` for ``void`` a function not returning anything. Use ``None`` for :ctype:`void`, a function not returning anything.
It is possible to assign a callable Python object that is not a ctypes It is possible to assign a callable Python object that is not a ctypes
type, in this case the function is assumed to return a C ``int``, and the type, in this case the function is assumed to return a C :ctype:`int`, and
callable will be called with this integer, allowing to do further the callable will be called with this integer, allowing to do further
processing or error checking. Using this is deprecated, for more flexible processing or error checking. Using this is deprecated, for more flexible
post processing or error checking use a ctypes data type as post processing or error checking use a ctypes data type as
:attr:`restype` and assign a callable to the :attr:`errcheck` attribute. :attr:`restype` and assign a callable to the :attr:`errcheck` attribute.
@ -1553,16 +1555,16 @@ They are instances of a private class:
:noindex: :noindex:
:module: :module:
*result* is what the foreign function returns, as specified *result* is what the foreign function returns, as specified by the
by the :attr:`restype` attribute. :attr:`restype` attribute.
*func* is the foreign function object itself, this allows *func* is the foreign function object itself, this allows to reuse the
to reuse the same callable object to check or post process same callable object to check or post process the results of several
the results of several functions. functions.
*arguments* is a tuple containing the parameters originally *arguments* is a tuple containing the parameters originally passed to
passed to the function call, this allows to specialize the the function call, this allows to specialize the behavior on the
behavior on the arguments used. arguments used.
The object that this function returns will be returned from the The object that this function returns will be returned from the
foreign function call, but it can also check the result value foreign function call, but it can also check the result value
@ -1633,11 +1635,10 @@ different ways, depending on the type and number of the parameters in the call:
:noindex: :noindex:
:module: :module:
Returns a foreign function exported by a shared library. *func_spec* Returns a foreign function exported by a shared library. *func_spec* must
must be a 2-tuple ``(name_or_ordinal, library)``. The first item is the be a 2-tuple ``(name_or_ordinal, library)``. The first item is the name of
name of the exported function as string, or the ordinal of the exported the exported function as string, or the ordinal of the exported function
function as small integer. The second item is the shared library as small integer. The second item is the shared library instance.
instance.
.. function:: prototype(vtbl_index, name[, paramflags[, iid]]) .. function:: prototype(vtbl_index, name[, paramflags[, iid]])
@ -1776,17 +1777,16 @@ Utility functions
.. function:: byref(obj[, offset]) .. function:: byref(obj[, offset])
Returns a light-weight pointer to *obj*, which must be an Returns a light-weight pointer to *obj*, which must be an instance of a
instance of a ctypes type. *offset* defaults to zero, and must be ctypes type. *offset* defaults to zero, and must be an integer that will be
an integer that will be added to the internal pointer value. added to the internal pointer value.
``byref(obj, offset)`` corresponds to this C code:: ``byref(obj, offset)`` corresponds to this C code::
(((char *)&obj) + offset) (((char *)&obj) + offset)
The returned object can only be used as a foreign function call The returned object can only be used as a foreign function call parameter.
parameter. It behaves similar to ``pointer(obj)``, but the It behaves similar to ``pointer(obj)``, but the construction is a lot faster.
construction is a lot faster.
.. function:: cast(obj, type) .. function:: cast(obj, type)
@ -1834,16 +1834,17 @@ Utility functions
.. function:: DllCanUnloadNow() .. function:: DllCanUnloadNow()
Windows only: This function is a hook which allows to implement in-process COM Windows only: This function is a hook which allows to implement in-process
servers with ctypes. It is called from the DllCanUnloadNow function that the COM servers with ctypes. It is called from the DllCanUnloadNow function that
_ctypes extension dll exports. the _ctypes extension dll exports.
.. function:: DllGetClassObject() .. function:: DllGetClassObject()
Windows only: This function is a hook which allows to implement in-process COM Windows only: This function is a hook which allows to implement in-process
servers with ctypes. It is called from the DllGetClassObject function that the COM servers with ctypes. It is called from the DllGetClassObject function
``_ctypes`` extension dll exports. that the ``_ctypes`` extension dll exports.
.. function:: find_library(name) .. function:: find_library(name)
:module: ctypes.util :module: ctypes.util
@ -1859,19 +1860,20 @@ Utility functions
.. function:: find_msvcrt() .. function:: find_msvcrt()
:module: ctypes.util :module: ctypes.util
Windows only: return the filename of the VC runtype library used Windows only: return the filename of the VC runtype library used by Python,
by Python, and by the extension modules. If the name of the and by the extension modules. If the name of the library cannot be
library cannot be determined, ``None`` is returned. 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.
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.
.. function:: FormatError([code]) .. function:: FormatError([code])
Windows only: Returns a textual description of the error code. If no error code Windows only: Returns a textual description of the error code *code*. If no
is specified, the last error code is used by calling the Windows api function error code is specified, the last error code is used by calling the Windows
GetLastError. api function GetLastError.
.. function:: GetLastError() .. function:: GetLastError()
@ -1893,8 +1895,8 @@ Utility functions
.. function:: memmove(dst, src, count) .. function:: memmove(dst, src, count)
Same as the standard C memmove library function: copies *count* bytes from 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 *src* to *dst*. *dst* and *src* must be integers or ctypes instances that can
can be converted to pointers. be converted to pointers.
.. function:: memset(dst, c, count) .. function:: memset(dst, c, count)
@ -1908,13 +1910,13 @@ Utility functions
This factory function creates and returns a new ctypes pointer type. Pointer This factory function creates and returns a new ctypes pointer type. Pointer
types are cached an reused internally, so calling this function repeatedly is types are cached an reused internally, so calling this function repeatedly is
cheap. type must be a ctypes type. cheap. *type* must be a ctypes type.
.. function:: pointer(obj) .. function:: pointer(obj)
This function creates a new pointer instance, pointing to *obj*. The returned This function creates a new pointer instance, pointing to *obj*. The returned
object is of the type POINTER(type(obj)). object is of the type ``POINTER(type(obj))``.
Note: If you just want to pass a pointer to an object to a foreign function Note: If you just want to pass a pointer to an object to a foreign function
call, you should use ``byref(obj)`` which is much faster. call, you should use ``byref(obj)`` which is much faster.
@ -1922,10 +1924,10 @@ Utility functions
.. function:: resize(obj, size) .. function:: resize(obj, size)
This function resizes the internal memory buffer of obj, which must be an This function resizes the internal memory buffer of *obj*, which must be an
instance of a ctypes type. It is not possible to make the buffer smaller than instance of a ctypes type. It is not possible to make the buffer smaller
the native size of the objects type, as given by ``sizeof(type(obj))``, but than the native size of the objects type, as given by ``sizeof(type(obj))``,
it is possible to enlarge the buffer. but it is possible to enlarge the buffer.
.. function:: set_conversion_mode(encoding, errors) .. function:: set_conversion_mode(encoding, errors)
@ -1936,9 +1938,9 @@ Utility functions
the error handling on encoding/decoding errors. Examples of possible values are the error handling on encoding/decoding errors. Examples of possible values are
``'strict'``, ``'replace'``, or ``'ignore'``. ``'strict'``, ``'replace'``, or ``'ignore'``.
:func:`set_conversion_mode` returns a 2-tuple containing the previous conversion :func:`set_conversion_mode` returns a 2-tuple containing the previous
rules. On windows, the initial conversion rules are ``('mbcs', 'ignore')``, on conversion rules. On windows, the initial conversion rules are ``('mbcs',
other systems ``('ascii', 'strict')``. 'ignore')``, on other systems ``('ascii', 'strict')``.
You can set the *encoding* to ``'undefined'`` to completely disable automatic You can set the *encoding* to ``'undefined'`` to completely disable automatic
conversions. conversions.
@ -1950,6 +1952,7 @@ Utility functions
variable in the calling thread to *value* and return the previous value. variable in the calling thread to *value* and return the previous value.
.. function:: set_last_error(value) .. function:: set_last_error(value)
Windows only: set the current value of the ctypes-private copy of the system Windows only: set the current value of the ctypes-private copy of the system
@ -1957,6 +1960,7 @@ Utility functions
previous value. previous value.
.. function:: sizeof(obj_or_type) .. function:: sizeof(obj_or_type)
Returns the size in bytes of a ctypes type or instance memory buffer. Does the Returns the size in bytes of a ctypes type or instance memory buffer. Does the
@ -1974,7 +1978,7 @@ Utility functions
Windows only: this function is probably the worst-named thing in ctypes. It Windows only: this function is probably the worst-named thing in ctypes. It
creates an instance of WindowsError. If *code* is not specified, creates an instance of WindowsError. If *code* is not specified,
``GetLastError`` is called to determine the error code. If ``descr`` is not ``GetLastError`` is called to determine the error code. If *descr* is not
specified, :func:`FormatError` is called to get a textual description of the specified, :func:`FormatError` is called to get a textual description of the
error. error.
@ -1982,8 +1986,8 @@ Utility functions
.. function:: wstring_at(address, size=-1) .. function:: wstring_at(address, size=-1)
This function returns the wide character string starting at memory address This function returns the wide character string starting at memory address
*address* as a string. If ``size`` is specified, it is used as the *address* as a string. If *size* is specified, it is used as the number of
number of characters of the string, otherwise the string is assumed to be characters of the string, otherwise the string is assumed to be
zero-terminated. zero-terminated.
@ -1995,37 +1999,37 @@ Data types
.. class:: _CData .. class:: _CData
This non-public class is the common base class of all ctypes data types. Among This non-public class is the common base class of all ctypes data types.
other things, all ctypes type instances contain a memory block that hold C Among other things, all ctypes type instances contain a memory block that
compatible data; the address of the memory block is returned by the hold C compatible data; the address of the memory block is returned by the
:func:`addressof` helper function. Another instance variable is exposed as :func:`addressof` helper function. Another instance variable is exposed as
:attr:`_objects`; this contains other Python objects that need to be kept alive :attr:`_objects`; this contains other Python objects that need to be kept
in case the memory block contains pointers. alive in case the memory block contains pointers.
Common methods of ctypes data types, these are all class methods (to be Common methods of ctypes data types, these are all class methods (to be
exact, they are methods of the :term:`metaclass`): exact, they are methods of the :term:`metaclass`):
.. method:: _CData.from_buffer(source[, offset]) .. method:: _CData.from_buffer(source[, offset])
This method returns a ctypes instance that shares the buffer of This method returns a ctypes instance that shares the buffer of the
the ``source`` object. The ``source`` object must support the *source* object. The *source* object must support the writeable buffer
writeable buffer interface. The optional ``offset`` parameter interface. The optional *offset* parameter specifies an offset into the
specifies an offset into the source buffer in bytes; the default source buffer in bytes; the default is zero. If the source buffer is not
is zero. If the source buffer is not large enough a ValueError large enough a :exc:`ValueError` is raised.
is raised.
.. method:: _CData.from_buffer_copy(source[, offset]) .. method:: _CData.from_buffer_copy(source[, offset])
This method creates a ctypes instance, copying the buffer from This method creates a ctypes instance, copying the buffer from the
the source object buffer which must be readable. The optional *source* object buffer which must be readable. The optional *offset*
*offset* parameter specifies an offset into the source buffer parameter specifies an offset into the source buffer in bytes; the default
in bytes; the default is zero. If the source buffer is not is zero. If the source buffer is not large enough a :exc:`ValueError` is
large enough a ValueError is raised. raised.
.. method:: from_address(address) .. method:: from_address(address)
This method returns a ctypes type instance using the memory specified by This method returns a ctypes type instance using the memory specified by
address which must be an integer. *address* which must be an integer.
.. method:: from_param(obj) .. method:: from_param(obj)
@ -2111,193 +2115,195 @@ These are the fundamental ctypes data types:
.. class:: c_byte .. class:: c_byte
Represents the C signed char datatype, and interprets the value as small Represents the C :ctype:`signed char` datatype, and interprets the value as
integer. The constructor accepts an optional integer initializer; no overflow small integer. The constructor accepts an optional integer initializer; no
checking is done. overflow checking is done.
.. class:: c_char .. class:: c_char
Represents the C char datatype, and interprets the value as a single character. Represents the C :ctype:`char` datatype, and interprets the value as a single
The constructor accepts an optional string initializer, the length of the string character. The constructor accepts an optional string initializer, the
must be exactly one character. length of the string must be exactly one character.
.. class:: c_char_p .. class:: c_char_p
Represents the C char \* datatype, which must be a pointer to a zero-terminated Represents the C :ctype:`char *` datatype when it points to a zero-terminated
string. The constructor accepts an integer address, or a bytes object. string. For a general character pointer that may also point to binary data,
``POINTER(c_char)`` must be used. The constructor accepts an integer
address, or a bytes object.
.. class:: c_double .. class:: c_double
Represents the C double datatype. The constructor accepts an optional float Represents the C :ctype:`double` datatype. The constructor accepts an
initializer. optional float initializer.
.. class:: c_longdouble .. class:: c_longdouble
Represents the C long double datatype. The constructor accepts an Represents the C :ctype:`long double` datatype. The constructor accepts an
optional float initializer. On platforms where ``sizeof(long optional float initializer. On platforms where ``sizeof(long double) ==
double) == sizeof(double)`` it is an alias to :class:`c_double`. sizeof(double)`` it is an alias to :class:`c_double`.
.. class:: c_float .. class:: c_float
Represents the C float datatype. The constructor accepts an optional float Represents the C :ctype:`float` datatype. The constructor accepts an
initializer. optional float initializer.
.. class:: c_int .. class:: c_int
Represents the C signed int datatype. The constructor accepts an optional Represents the C :ctype:`signed int` datatype. The constructor accepts an
integer initializer; no overflow checking is done. On platforms where optional integer initializer; no overflow checking is done. On platforms
``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`. where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`.
.. class:: c_int8 .. class:: c_int8
Represents the C 8-bit ``signed int`` datatype. Usually an alias for Represents the C 8-bit :ctype:`signed int` datatype. Usually an alias for
:class:`c_byte`. :class:`c_byte`.
.. class:: c_int16 .. class:: c_int16
Represents the C 16-bit signed int datatype. Usually an alias for Represents the C 16-bit :ctype:`signed int` datatype. Usually an alias for
:class:`c_short`. :class:`c_short`.
.. class:: c_int32 .. class:: c_int32
Represents the C 32-bit signed int datatype. Usually an alias for Represents the C 32-bit :ctype:`signed int` datatype. Usually an alias for
:class:`c_int`. :class:`c_int`.
.. class:: c_int64 .. class:: c_int64
Represents the C 64-bit ``signed int`` datatype. Usually an alias for Represents the C 64-bit :ctype:`signed int` datatype. Usually an alias for
:class:`c_longlong`. :class:`c_longlong`.
.. class:: c_long .. class:: c_long
Represents the C ``signed long`` datatype. The constructor accepts an optional Represents the C :ctype:`signed long` datatype. The constructor accepts an
integer initializer; no overflow checking is done. optional integer initializer; no overflow checking is done.
.. class:: c_longlong .. class:: c_longlong
Represents the C ``signed long long`` datatype. The constructor accepts an Represents the C :ctype:`signed long long` datatype. The constructor accepts
optional integer initializer; no overflow checking is done. an optional integer initializer; no overflow checking is done.
.. class:: c_short .. class:: c_short
Represents the C ``signed short`` datatype. The constructor accepts an optional Represents the C :ctype:`signed short` datatype. The constructor accepts an
integer initializer; no overflow checking is done. optional integer initializer; no overflow checking is done.
.. class:: c_size_t .. class:: c_size_t
Represents the C ``size_t`` datatype. Represents the C :ctype:`size_t` datatype.
.. class:: c_ubyte .. class:: c_ubyte
Represents the C ``unsigned char`` datatype, it interprets the value as small Represents the C :ctype:`unsigned char` datatype, it interprets the value as
integer. The constructor accepts an optional integer initializer; no overflow small integer. The constructor accepts an optional integer initializer; no
checking is done. overflow checking is done.
.. class:: c_uint .. class:: c_uint
Represents the C ``unsigned int`` datatype. The constructor accepts an optional Represents the C :ctype:`unsigned int` datatype. The constructor accepts an
integer initializer; no overflow checking is done. On platforms where optional integer initializer; no overflow checking is done. On platforms
``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`. where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`.
.. class:: c_uint8 .. class:: c_uint8
Represents the C 8-bit unsigned int datatype. Usually an alias for Represents the C 8-bit :ctype:`unsigned int` datatype. Usually an alias for
:class:`c_ubyte`. :class:`c_ubyte`.
.. class:: c_uint16 .. class:: c_uint16
Represents the C 16-bit unsigned int datatype. Usually an alias for Represents the C 16-bit :ctype:`unsigned int` datatype. Usually an alias for
:class:`c_ushort`. :class:`c_ushort`.
.. class:: c_uint32 .. class:: c_uint32
Represents the C 32-bit unsigned int datatype. Usually an alias for Represents the C 32-bit :ctype:`unsigned int` datatype. Usually an alias for
:class:`c_uint`. :class:`c_uint`.
.. class:: c_uint64 .. class:: c_uint64
Represents the C 64-bit unsigned int datatype. Usually an alias for Represents the C 64-bit :ctype:`unsigned int` datatype. Usually an alias for
:class:`c_ulonglong`. :class:`c_ulonglong`.
.. class:: c_ulong .. class:: c_ulong
Represents the C ``unsigned long`` datatype. The constructor accepts an optional Represents the C :ctype:`unsigned long` datatype. The constructor accepts an
integer initializer; no overflow checking is done. optional integer initializer; no overflow checking is done.
.. class:: c_ulonglong .. class:: c_ulonglong
Represents the C ``unsigned long long`` datatype. The constructor accepts an Represents the C :ctype:`unsigned long long` datatype. The constructor
optional integer initializer; no overflow checking is done. accepts an optional integer initializer; no overflow checking is done.
.. class:: c_ushort .. class:: c_ushort
Represents the C ``unsigned short`` datatype. The constructor accepts an Represents the C :ctype:`unsigned short` datatype. The constructor accepts
optional integer initializer; no overflow checking is done. an optional integer initializer; no overflow checking is done.
.. class:: c_void_p .. class:: c_void_p
Represents the C ``void *`` type. The value is represented as integer. The Represents the C :ctype:`void *` type. The value is represented as integer.
constructor accepts an optional integer initializer. The constructor accepts an optional integer initializer.
.. class:: c_wchar .. class:: c_wchar
Represents the C ``wchar_t`` datatype, and interprets the value as a single Represents the C :ctype:`wchar_t` datatype, and interprets the value as a
character unicode string. The constructor accepts an optional string single character unicode string. The constructor accepts an optional string
initializer, the length of the string must be exactly one character. initializer, the length of the string must be exactly one character.
.. class:: c_wchar_p .. class:: c_wchar_p
Represents the C ``wchar_t *`` datatype, which must be a pointer to a Represents the C :ctype:`wchar_t *` datatype, which must be a pointer to a
zero-terminated wide character string. The constructor accepts an integer zero-terminated wide character string. The constructor accepts an integer
address, or a string. address, or a string.
.. class:: c_bool .. class:: c_bool
Represent the C ``bool`` datatype (more accurately, _Bool from C99). Its value Represent the C :ctype:`bool` datatype (more accurately, :ctype:`_Bool` from
can be True or False, and the constructor accepts any object that has a truth C99). Its value can be True or False, and the constructor accepts any object
value. that has a truth value.
.. class:: HRESULT .. class:: HRESULT
Windows only: Represents a :class:`HRESULT` value, which contains success or Windows only: Represents a :ctype:`HRESULT` value, which contains success or
error information for a function or method call. error information for a function or method call.
.. class:: py_object .. class:: py_object
Represents the C ``PyObject *`` datatype. Calling this without an argument Represents the C :ctype:`PyObject *` datatype. Calling this without an
creates a ``NULL`` ``PyObject *`` pointer. argument creates a ``NULL`` :ctype:`PyObject *` pointer.
The ``ctypes.wintypes`` module provides quite some other Windows specific data The :mod:`ctypes.wintypes` module provides quite some other Windows specific
types, for example ``HWND``, ``WPARAM``, or ``DWORD``. Some useful structures data types, for example :ctype:`HWND`, :ctype:`WPARAM`, or :ctype:`DWORD`. Some
like ``MSG`` or ``RECT`` are also defined. useful structures like :ctype:`MSG` or :ctype:`RECT` are also defined.
.. _ctypes-structured-data-types: .. _ctypes-structured-data-types:
@ -2382,8 +2388,8 @@ other data types containing pointer type fields.
.. attribute:: _anonymous_ .. attribute:: _anonymous_
An optional sequence that lists the names of unnamed (anonymous) fields. An optional sequence that lists the names of unnamed (anonymous) fields.
``_anonymous_`` must be already defined when :attr:`_fields_` is assigned, :attr:`_anonymous_` must be already defined when :attr:`_fields_` is
otherwise it will have no effect. assigned, otherwise it will have no effect.
The fields listed in this variable must be structure or union type fields. The fields listed in this variable must be structure or union type fields.
:mod:`ctypes` will create descriptors in the structure type that allows to :mod:`ctypes` will create descriptors in the structure type that allows to
@ -2415,17 +2421,17 @@ other data types containing pointer type fields.
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 It is possible to defined sub-subclasses of structures, they inherit the
of the base class. If the subclass definition has a separate :attr:`_fields_` fields of the base class. If the subclass definition has a separate
variable, the fields specified in this are appended to the fields of the base :attr:`_fields_` variable, the fields specified in this are appended to the
class. fields of the base class.
Structure and union constructors accept both positional and keyword arguments. Structure and union constructors accept both positional and keyword
Positional arguments are used to initialize member fields in the same order as arguments. Positional arguments are used to initialize member fields in the
they are appear in :attr:`_fields_`. Keyword arguments in the constructor are same order as they are appear in :attr:`_fields_`. Keyword arguments in the
interpreted as attribute assignments, so they will initialize :attr:`_fields_` constructor are interpreted as attribute assignments, so they will initialize
with the same name, or create new attributes for names not present in :attr:`_fields_` with the same name, or create new attributes for names not
:attr:`_fields_`. present in :attr:`_fields_`.
.. _ctypes-arrays-pointers: .. _ctypes-arrays-pointers:
@ -2433,6 +2439,6 @@ with the same name, or create new attributes for names not present in
Arrays and pointers Arrays and pointers
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
Not yet written - please see the sections :ref:`ctypes-pointers` and Not yet written - please see the sections :ref:`ctypes-pointers` and section
section :ref:`ctypes-arrays` in the tutorial. :ref:`ctypes-arrays` in the tutorial.