Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Merged revisions 77110 via svnmerge from 

svn+ssh://svn.python.org/python/branches/py3k

................
  r77110 | georg.brandl | 2009-12-29 12:24:00 +0100 (Di, 29 Dez 2009) | 13 lines

  Merged revisions 77108-77109 via svnmerge from
  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:26:06 +00:00
parent d56a5d7156
commit b91f68f152
1 changed files with 235 additions and 229 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

464
Doc/library/ctypes.rst
View File

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