diff options
Diffstat (limited to 'Doc/library/ctypes.rst')
| -rw-r--r-- | Doc/library/ctypes.rst | 191 |
1 files changed, 101 insertions, 90 deletions
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index fccb1a0..61c1e61 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -40,7 +40,7 @@ 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 :class:`WindowsError` Python exceptions when +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 @@ -55,10 +55,10 @@ convention:: >>> libc = cdll.msvcrt # doctest: +WINDOWS >>> -Windows appends the usual '.dll' file suffix automatically. +Windows appends the usual ``.dll`` file suffix automatically. On Linux, it is required to specify the filename *including* the extension to -load a library, so attribute access does not work. Either the +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:: @@ -107,7 +107,7 @@ UNICODE is defined or not:: *windll* does not try to select one of them by magic, you must access the version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW`` -explicitly, and then call it with normal strings or unicode strings +explicitly, and then call it with strings or unicode strings respectively. Sometimes, dlls export functions with names which aren't valid Python @@ -422,9 +422,9 @@ to implement a :meth:`from_param` class method for them to be able to use them in the :attr:`argtypes` sequence. The :meth:`from_param` class method receives the Python object passed to the function call, it should do a typecheck or whatever is needed to make sure this object is acceptable, and then return the -object itself, it's :attr:`_as_parameter_` attribute, or whatever you want to +object itself, its :attr:`_as_parameter_` attribute, or whatever you want to pass as the C function argument in this case. Again, the result should be an -integer, string, unicode, a ``ctypes`` instance, or something having the +integer, string, unicode, a ``ctypes`` instance, or an object with an :attr:`_as_parameter_` attribute. @@ -719,6 +719,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. + Pointer instances can also be indexed with integers:: >>> pi[0] @@ -765,7 +767,7 @@ Calling the pointer type without an argument creates a ``NULL`` pointer. >>> ``ctypes`` checks for ``NULL`` when dereferencing pointers (but dereferencing -non-\ ``NULL`` pointers would crash Python):: +invalid non-\ ``NULL`` pointers would crash Python):: >>> null_ptr[0] Traceback (most recent call last): @@ -811,9 +813,9 @@ To set a POINTER type field to ``NULL``, you can assign ``None``:: >>> bar.values = None >>> -XXX list other conversions... +.. XXX list other conversions... -Sometimes you have instances of incompatible types. In ``C``, you can cast one +Sometimes you have instances of incompatible types. In C, you can cast one type into another type. ``ctypes`` provides a ``cast`` function which can be used in the same way. The ``Bar`` structure defined above accepts ``POINTER(c_int)`` pointers or :class:`c_int` arrays for its ``values`` field, @@ -1070,7 +1072,7 @@ crashing your program when a callback is made. Accessing values exported from dlls ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sometimes, a dll not only exports functions, it also exports variables. An +Some shared libraries not only export functions, they also export variables. An example in the Python library itself is the ``Py_OptimizeFlag``, an integer set to 0, 1, or 2, depending on the :option:`-O` or :option:`-OO` flag given on startup. @@ -1246,17 +1248,6 @@ dynamic nature of Python, and (re-)define the data type after the required size is already known, on a case by case basis. -.. _ctypes-bugs-todo-non-implemented-things: - -Bugs, ToDo and non-implemented things -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Enumeration types are not implemented. You can do it easily yourself, using -:class:`c_int` as the base class. - -``long double`` is not implemented. - - .. _ctypes-ctypes-reference: ctypes reference @@ -1615,9 +1606,8 @@ type and the argument types of the function. `use_last_error` does the same for the Windows error code. .. versionchanged:: 2.6 - - The optional `use_errno` and `use_last_error` parameters were added - in Python 2.6. + The optional `use_errno` and `use_last_error` parameters were + added. .. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) @@ -1633,75 +1623,71 @@ type and the argument types of the function. The returned function prototype creates functions that use the Python calling convention. The function will *not* release the GIL during the call. -Function prototypes created by the factory functions can be instantiated in -different ways, depending on the type and number of the parameters in the call. - - -.. function:: prototype(address) - :noindex: - - Returns a foreign function at the specified address. - - -.. function:: prototype(callable) - :noindex: - - Create a C callable function (a callback function) from a Python ``callable``. +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: -.. function:: prototype(func_spec[, paramflags]) - :noindex: + .. function:: prototype(address) + :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 at the specified address which must be an integer. -.. function:: prototype(vtbl_index, name[, paramflags[, iid]]) - :noindex: + .. function:: prototype(callable) + :noindex: + :module: - Returns a foreign function that will call a COM method. ``vtbl_index`` is the - 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 - which is used in extended error reporting. + Create a C callable function (a callback function) from a Python ``callable``. - 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 - in the :attr:`argtypes` tuple. -The optional *paramflags* parameter creates foreign function wrappers with much -more functionality than the features described above. + .. function:: prototype(func_spec[, paramflags]) + :noindex: + :module: -*paramflags* must be a tuple of the same length as :attr:`argtypes`. + 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. -Each item in this tuple contains further information about a parameter, it must -be a tuple containing 1, 2, or 3 items. -The first item is an integer containing flags for the parameter: + .. function:: prototype(vtbl_index, name[, paramflags[, iid]]) + :noindex: + :module: + Returns a foreign function that will call a COM method. ``vtbl_index`` is the + 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 + which is used in extended error reporting. -.. data:: 1 - :noindex: + 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 + in the :attr:`argtypes` tuple. - Specifies an input parameter to the function. + The optional *paramflags* parameter creates foreign function wrappers with much + more functionality than the features described above. + *paramflags* must be a tuple of the same length as :attr:`argtypes`. -.. data:: 2 - :noindex: + Each item in this tuple contains further information about a parameter, it must + be a tuple containing one, two, or three items. - Output parameter. The foreign function fills in a value. + The first item is an integer containing a combination of direction + flags for the parameter: + 1 + Specifies an input parameter to the function. -.. data:: 4 - :noindex: + 2 + Output parameter. The foreign function fills in a value. - Input parameter which defaults to the integer zero. + 4 + Input parameter which defaults to the integer zero. -The optional second item is the parameter name as string. If this is specified, -the foreign function can be called with named parameters. + The optional second item is the parameter name as string. If this is specified, + the foreign function can be called with named parameters. -The optional third item is the default value for this parameter. + 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 @@ -1714,16 +1700,14 @@ the windows header file is this:: LPCSTR lpCaption, UINT uType); -Here is the wrapping with ``ctypes``: +Here is the wrapping with ``ctypes``:: - :: - - >>> from ctypes import c_int, WINFUNCTYPE, windll - >>> from ctypes.wintypes import HWND, LPCSTR, UINT - >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT) - >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) - >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags) - >>> + >>> from ctypes import c_int, WINFUNCTYPE, windll + >>> from ctypes.wintypes import HWND, LPCSTR, UINT + >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT) + >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) + >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags) + >>> The MessageBox foreign function can now be called in these ways:: @@ -1741,16 +1725,14 @@ function retrieves the dimensions of a specified window by copying them into HWND hWnd, LPRECT lpRect); -Here is the wrapping with ``ctypes``: - - :: +Here is the wrapping with ``ctypes``:: - >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError - >>> from ctypes.wintypes import BOOL, HWND, RECT - >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) - >>> paramflags = (1, "hwnd"), (2, "lprect") - >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags) - >>> + >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError + >>> from ctypes.wintypes import BOOL, HWND, RECT + >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) + >>> paramflags = (1, "hwnd"), (2, "lprect") + >>> 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 @@ -1766,6 +1748,7 @@ do the error checking, and raises an exception when the api call failed:: ... if not result: ... raise WinError() ... return args + ... >>> GetWindowRect.errcheck = errcheck >>> @@ -1780,7 +1763,7 @@ instead, the normal processing will no longer take place:: ... raise WinError() ... rc = args[1] ... return rc.left, rc.top, rc.bottom, rc.right - >>> + ... >>> GetWindowRect.errcheck = errcheck >>> @@ -1866,6 +1849,33 @@ Utility functions servers with ctypes. It is called from the DllGetClassObject function that the ``_ctypes`` extension dll exports. +.. 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]) @@ -2154,6 +2164,7 @@ These are the fundamental ctypes data types: optional float initializer. On platforms where ``sizeof(long double) == sizeof(double)`` it is an alias to :class:`c_double`. + .. versionadded:: 2.6 .. class:: c_float |