ctypes —- Python 的外部函数库

ctypes 是 Python 的外部函数库。它提供了与 C 兼容的数据类型，并允许调用 DLL 或共享库中的函数。可使用该模块以纯 Python 形式对这些库进行封装。

ctypes 教程

注意：在本教程中的示例代码使用 doctest 进行过测试，保证其正确运行。由于有些代码在Linux，Windows或Mac OS X下的表现不同，这些代码会在 doctest 中包含相关的指令注解。

注意：部分示例代码引用了 ctypes c_int 类型。在 sizeof(long) == sizeof(int) 的平台上此类型是 c_long 的一个别名。所以，在程序输出 c_long 而不是你期望的 c_int 时不必感到迷惑 —- 它们实际上是同一种类型。

载入动态连接库

ctypes 导出了 cdll 对象，在 Windows 系统中还导出了 windll 和 oledll 对象用于载入动态连接库。

通过操作这些对象的属性，你可以载入外部的动态链接库。cdll 载入按标准的 cdecl 调用协议导出的函数，而 windll 导入的库按 stdcall 调用协议调用其中的函数。 oledll 也按 stdcall 调用协议调用其中的函数，并假定该函数返回的是 Windows HRESULT 错误代码，并当函数调用失败时，自动根据该代码甩出一个 OSError 异常。

在 3.3 版更改: 原来在 Windows 下甩出的异常类型 WindowsError 现在是 OSError 的一个别名。

这是一些 Windows 下的例子。注意：msvcrt 是微软 C 标准库，包含了大部分 C 标准函数，这些函数都是以 cdecl 调用协议进行调用的。

  1. >>> from ctypes import *
  2. >>> print(windll.kernel32)  
  3. <WinDLL 'kernel32', handle ... at ...>
  4. >>> print(cdll.msvcrt)      
  5. <CDLL 'msvcrt', handle ... at ...>
  6. >>> libc = cdll.msvcrt      
  7. >>>

Windows会自动添加通常的 .dll 文件扩展名。

注解

通过 cdll.msvcrt 调用的标准 C 函数，可能会导致调用一个过时的，与当前 Python 所不兼容的函数。因此，请尽量使用标准的 Python 函数，而不要使用 msvcrt 模块。

在 Linux 下，必须使用 包含 文件扩展名的文件名来导入共享库。因此不能简单使用对象属性的方式来导入库。因此，你可以使用方法 LoadLibrary()，或构造 CDLL 对象来导入库。

  1. >>> cdll.LoadLibrary("libc.so.6")  
  2. <CDLL 'libc.so.6', handle ... at ...>
  3. >>> libc = CDLL("libc.so.6")       
  4. >>> libc                           
  5. <CDLL 'libc.so.6', handle ... at ...>
  6. >>>

操作导入的动态链接库中的函数

通过操作dll对象的属性来操作这些函数。

  1. >>> from ctypes import *
  2. >>> libc.printf
  3. <_FuncPtr object at 0x...>
  4. >>> print(windll.kernel32.GetModuleHandleA)  
  5. <_FuncPtr object at 0x...>
  6. >>> print(windll.kernel32.MyOwnFunction)     
  7. Traceback (most recent call last):
  8.   File "<stdin>", line 1, in <module>
  9.   File "ctypes.py", line 239, in __getattr__
  10.     func = _StdcallFuncPtr(name, self)
  11. AttributeError: function 'MyOwnFunction' not found
  12. >>>

注意：Win32系统的动态库，比如 kernel32 和 user32，通常会同时导出同一个函数的 ANSI 版本和 UNICODE 版本。UNICODE 版本通常会在名字最后以 W 结尾，而 ANSI 版本的则以 A 结尾。 win32的 GetModuleHandle 函数会根据一个模块名返回一个 模块句柄，该函数暨同时包含这样的两个版本的原型函数，并通过宏 UNICODE 是否定义，来决定宏 GetModuleHandle 导出的是哪个具体函数。

  1. /* ANSI version */
  2. HMODULE GetModuleHandleA(LPCSTR lpModuleName);
  3. /* UNICODE version */
  4. HMODULE GetModuleHandleW(LPCWSTR lpModuleName);

windll 不会通过这样的魔法手段来帮你决定选择哪一种函数，你必须显式的调用 GetModuleHandleA 或 GetModuleHandleW，并分别使用字节对象或字符串对象作参数。

有时候，dlls的导出的函数名不符合 Python 的标识符规范，比如 "??2@YAPAXI@Z"。此时，你必须使用 getattr() 方法来获得该函数。

  1. >>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")  
  2. <_FuncPtr object at 0x...>
  3. >>>

Windows 下，有些 dll 导出的函数没有函数名，而是通过其顺序号调用。对此类函数，你也可以通过 dll 对象的数值索引来操作这些函数。

  1. >>> cdll.kernel32[1]  
  2. <_FuncPtr object at 0x...>
  3. >>> cdll.kernel32[0]  
  4. Traceback (most recent call last):
  5.   File "<stdin>", line 1, in <module>
  6.   File "ctypes.py", line 310, in __getitem__
  7.     func = _StdcallFuncPtr(name, self)
  8. AttributeError: function ordinal 0 not found
  9. >>>

调用函数

你可以貌似是调用其它 Python 函数那样直接调用这些函数。在这个例子中，我们调用了 time() 函数，该函数返回一个系统时间戳（从 Unix 时间起点到现在的秒数），而GetModuleHandleA() 函数返回一个 win32 模块句柄。

This example calls both functions with a NULL pointer (None should be usedas the NULL pointer):

  1. >>> print(libc.time(None))  
  2. 1150640792
  3. >>> print(hex(windll.kernel32.GetModuleHandleA(None)))  
  4. 0x1d000000
  5. >>>

注解

调用该函数，若 ctypes 发现传入的参数个数不符，则会甩出一个异常 ValueError。但该行为并不可靠。它在 3.6.2 中被废弃，会在 3.7 中彻底移除。

如果你用 cdecl 调用方式调用 stdcall 约定的函数，则会甩出一个异常 ValueError。反之亦然。

  1. >>> cdll.kernel32.GetModuleHandleA(None)  
  2. Traceback (most recent call last):
  3.   File "<stdin>", line 1, in <module>
  4. ValueError: Procedure probably called with not enough arguments (4 bytes missing)
  5. >>>
  6.  
  7. >>> windll.msvcrt.printf(b"spam")  
  8. Traceback (most recent call last):
  9.   File "<stdin>", line 1, in <module>
  10. ValueError: Procedure probably called with too many arguments (4 bytes in excess)
  11. >>>

你必须阅读这些库的头文件或说明文档来确定它们的调用协议。

在Windows中，ctypes 使用 win32 结构化异常处理来防止由于在调用函数时使用非法参数导致的程序崩溃。

  1. >>> windll.kernel32.GetModuleHandleA(32)  
  2. Traceback (most recent call last):
  3.   File "<stdin>", line 1, in <module>
  4. OSError: exception: access violation reading 0x00000020
  5. >>>

然而，总有许多办法，通过调用 ctypes 使得 Python 程序崩溃。因此，你必须小心使用。 faulthandler 模块可以用于帮助诊断程序崩溃的原因。（比如由于错误的C库函数调用导致的段错误）。

None，整型，字节对象和（UNICODE）字符串是仅有的可以直接作为函数参数使用的四种Python本地数据类型。None` 作为C的空指针 (NULL)，字节和字符串类型作为一个指向其保存数据的内存块指针 （char 或 wchar_t )。Python 的整型则作为平台默认的C的 int 类型，他们的数值被截断以适应C类型的整型长度。

在我们开始调用函数前，我们必须先了解作为函数参数的 ctypes 数据类型。

基础数据类型

ctypes 定义了一些和C兼容的基本数据类型：

ctypes 类型C 类型Python 数据类型
c_bool_Boolbool (1)
c_charchar单字符字节对象
c_wcharwchar_t单字符字符串
c_bytecharint
c_ubyteunsigned charint
c_shortshortint
c_ushortunsigned shortint
c_intintint
c_uintunsigned intint
c_longlongint
c_ulongunsigned longint
c_longlongint64 或 long longint
c_ulonglongunsigned int64 或 unsigned long longint
c_size_tsize_tint
c_ssize_tssize_t 或 Py_ssize_tint
c_floatfloatfloat
c_doubledoublefloat
c_longdoublelong doublefloat
c_char_pchar (NUL terminated)字节串对象或 None
c_wchar_pwchar_t (NUL terminated)字符串或 None
c_void_pvoid *int 或 None
  • 构造函数接受任何具有真值的对象。

所有这些类型都可以通过使用正确类型和值的可选初始值调用它们来创建:

  1. >>> c_int()
  2. c_long(0)
  3. >>> c_wchar_p("Hello, World")
  4. c_wchar_p(140018365411392)
  5. >>> c_ushort(-3)
  6. c_ushort(65533)
  7. >>>

由于这些类型是可变的，它们的值也可以在以后更改:

  1. >>> i = c_int(42)
  2. >>> print(i)
  3. c_long(42)
  4. >>> print(i.value)
  5. 42
  6. >>> i.value = -99
  7. >>> print(i.value)
  8. -99
  9. >>>

当给指针类型的对象 c_char_p, c_wchar_p 和 c_void_p 等赋值时，将改变它们所指向的 内存地址，而 不是 它们所指向的内存区域的 内容 (这是理所当然的，因为 Python 的 bytes 对象是不可变的):

  1. >>> s = "Hello, World"
  2. >>> c_s = c_wchar_p(s)
  3. >>> print(c_s)
  4. c_wchar_p(139966785747344)
  5. >>> print(c_s.value)
  6. Hello World
  7. >>> c_s.value = "Hi, there"
  8. >>> print(c_s)              # the memory location has changed
  9. c_wchar_p(139966783348904)
  10. >>> print(c_s.value)
  11. Hi, there
  12. >>> print(s)                # first object is unchanged
  13. Hello, World
  14. >>>

但你要注意不能将它们传递给会改变指针所指内存的函数。如果你需要可改变的内存块，ctypes 提供了 create_string_buffer() 函数，它提供多种方式创建这种内存块。当前的内存块内容可以通过 raw 属性存取，如果你希望将它作为NUL结束的字符串，请使用 value 属性:

  1. >>> from ctypes import *
  2. >>> p = create_string_buffer(3)            # create a 3 byte buffer, initialized to NUL bytes
  3. >>> print(sizeof(p), repr(p.raw))
  4. 3 b'\x00\x00\x00'
  5. >>> p = create_string_buffer(b"Hello")     # create a buffer containing a NUL terminated string
  6. >>> print(sizeof(p), repr(p.raw))
  7. 6 b'Hello\x00'
  8. >>> print(repr(p.value))
  9. b'Hello'
  10. >>> p = create_string_buffer(b"Hello", 10) # create a 10 byte buffer
  11. >>> print(sizeof(p), repr(p.raw))
  12. 10 b'Hello\x00\x00\x00\x00\x00'
  13. >>> p.value = b"Hi"
  14. >>> print(sizeof(p), repr(p.raw))
  15. 10 b'Hi\x00lo\x00\x00\x00\x00\x00'
  16. >>>

create_string_buffer() 函数替代以前的ctypes版本中的 c_buffer() 函数 (仍然可当作别名使用)和 c_string() 函数。create_unicode_buffer() 函数创建包含 unicode 字符的可变内存块，与之对应的C语言类型是 wchar_t。

调用函数，继续

注意 printf 将打印到真正标准输出设备，而不是 sys.stdout，因此这些实例只能在控制台提示符下工作，而不能在 IDLE 或 PythonWin 中运行。

  1. >>> printf = libc.printf
  2. >>> printf(b"Hello, %s\n", b"World!")
  3. Hello, World!
  4. 14
  5. >>> printf(b"Hello, %S\n", "World!")
  6. Hello, World!
  7. 14
  8. >>> printf(b"%d bottles of beer\n", 42)
  9. 42 bottles of beer
  10. 19
  11. >>> printf(b"%f bottles of beer\n", 42.5)
  12. Traceback (most recent call last):
  13.   File "<stdin>", line 1, in <module>
  14. ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2
  15. >>>

正如前面所提到过的，除了整数、字符串以及字节串之外，所有的 Python 类型都必须使用它们对应的 ctypes 类型包装，才能够被正确地转换为所需的C语言类型。

  1. >>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
  2. An int 1234, a double 3.140000
  3. 31
  4. >>>

使用自定义的数据类型调用函数

You can also customize ctypes argument conversion to allow instances ofyour own classes be used as function arguments. ctypes looks for anas_parameter attribute and uses this as the function argument. Ofcourse, it must be one of integer, string, or bytes:

  1. >>> class Bottles:
  2. ...     def __init__(self, number):
  3. ...         self._as_parameter_ = number
  4. ...
  5. >>> bottles = Bottles(42)
  6. >>> printf(b"%d bottles of beer\n", bottles)
  7. 42 bottles of beer
  8. 19
  9. >>>

If you don't want to store the instance's data in the as_parameterinstance variable, you could define a property which makes theattribute available on request.

Specifying the required argument types (function prototypes)

It is possible to specify the required argument types of functions exported fromDLLs by setting the argtypes attribute.

argtypes must be a sequence of C data types (the printf function isprobably not a good example here, because it takes a variable number anddifferent types of parameters depending on the format string, on the other handthis is quite handy to experiment with this feature):

  1. >>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
  2. >>> printf(b"String '%s', Int %d, Double %f\n", b"Hi", 10, 2.2)
  3. String 'Hi', Int 10, Double 2.200000
  4. 37
  5. >>>

Specifying a format protects against incompatible argument types (just as aprototype for a C function), and tries to convert the arguments to valid types:

  1. >>> printf(b"%d %d %d", 1, 2, 3)
  2. Traceback (most recent call last):
  3.   File "<stdin>", line 1, in <module>
  4. ArgumentError: argument 2: exceptions.TypeError: wrong type
  5. >>> printf(b"%s %d %f\n", b"X", 2, 3)
  6. X 2 3.000000
  7. 13
  8. >>>

If you have defined your own classes which you pass to function calls, you haveto implement a fromparam() class method for them to be able to use themin the argtypes sequence. The from_param() class method receivesthe Python object passed to the function call, it should do a typecheck orwhatever is needed to make sure this object is acceptable, and then return theobject itself, its _as_parameter attribute, or whatever you want topass as the C function argument in this case. Again, the result should be aninteger, string, bytes, a ctypes instance, or an object with anas_parameter attribute.

Return types

By default functions are assumed to return the C int type. Otherreturn types can be specified by setting the restype attribute of thefunction object.

Here is a more advanced example, it uses the strchr function, which expectsa string pointer and a char, and returns a pointer to a string:

  1. >>> strchr = libc.strchr
  2. >>> strchr(b"abcdef", ord("d"))  
  3. 8059983
  4. >>> strchr.restype = c_char_p    # c_char_p is a pointer to a string
  5. >>> strchr(b"abcdef", ord("d"))
  6. b'def'
  7. >>> print(strchr(b"abcdef", ord("x")))
  8. None
  9. >>>

If you want to avoid the ord("x") calls above, you can set theargtypes attribute, and the second argument will be converted from asingle character Python bytes object into a C char:

  1. >>> strchr.restype = c_char_p
  2. >>> strchr.argtypes = [c_char_p, c_char]
  3. >>> strchr(b"abcdef", b"d")
  4. 'def'
  5. >>> strchr(b"abcdef", b"def")
  6. Traceback (most recent call last):
  7.   File "<stdin>", line 1, in <module>
  8. ArgumentError: argument 2: exceptions.TypeError: one character string expected
  9. >>> print(strchr(b"abcdef", b"x"))
  10. None
  11. >>> strchr(b"abcdef", b"d")
  12. 'def'
  13. >>>

You can also use a callable Python object (a function or a class for example) asthe restype attribute, if the foreign function returns an integer. Thecallable will be called with the integer the C function returns, and theresult of this call will be used as the result of your function call. This isuseful to check for error return values and automatically raise an exception:

  1. >>> GetModuleHandle = windll.kernel32.GetModuleHandleA  
  2. >>> def ValidHandle(value):
  3. ...     if value == 0:
  4. ...         raise WinError()
  5. ...     return value
  6. ...
  7. >>>
  8. >>> GetModuleHandle.restype = ValidHandle  
  9. >>> GetModuleHandle(None)  
  10. 486539264
  11. >>> GetModuleHandle("something silly")  
  12. Traceback (most recent call last):
  13.   File "<stdin>", line 1, in <module>
  14.   File "<stdin>", line 3, in ValidHandle
  15. OSError: [Errno 126] The specified module could not be found.
  16. >>>

WinError is a function which will call Windows FormatMessage() api toget the string representation of an error code, and returns an exception.WinError takes an optional error code parameter, if no one is used, it callsGetLastError() to retrieve it.

Please note that a much more powerful error checking mechanism is availablethrough the errcheck attribute; see the reference manual for details.

Passing pointers (or: passing parameters by reference)

Sometimes a C api function expects a pointer to a data type as parameter,probably to write into the corresponding location, or if the data is too largeto be passed by value. This is also known as passing parameters by reference.

ctypes exports the byref() function which is used to pass parametersby reference. The same effect can be achieved with the pointer() function,although pointer() does a lot more work since it constructs a real pointerobject, so it is faster to use byref() if you don't need the pointerobject in Python itself:

  1. >>> i = c_int()
  2. >>> f = c_float()
  3. >>> s = create_string_buffer(b'\000' * 32)
  4. >>> print(i.value, f.value, repr(s.value))
  5. 0 0.0 b''
  6. >>> libc.sscanf(b"1 3.14 Hello", b"%d %f %s",
  7. ...             byref(i), byref(f), s)
  8. 3
  9. >>> print(i.value, f.value, repr(s.value))
  10. 1 3.1400001049 b'Hello'
  11. >>>

Structures and unions

Structures and unions must derive from the Structure and Unionbase classes which are defined in the ctypes module. Each subclass mustdefine a fields attribute. fields must be a list of2-tuples, containing a field name and a field type.

The field type must be a ctypes type like c_int, or any otherderived ctypes type: structure, union, array, pointer.

Here is a simple example of a POINT structure, which contains two integers namedx and y, and also shows how to initialize a structure in the constructor:

  1. >>> from ctypes import *
  2. >>> class POINT(Structure):
  3. ...     _fields_ = [("x", c_int),
  4. ...                 ("y", c_int)]
  5. ...
  6. >>> point = POINT(10, 20)
  7. >>> print(point.x, point.y)
  8. 10 20
  9. >>> point = POINT(y=5)
  10. >>> print(point.x, point.y)
  11. 0 5
  12. >>> POINT(1, 2, 3)
  13. Traceback (most recent call last):
  14.   File "<stdin>", line 1, in <module>
  15. TypeError: too many initializers
  16. >>>

You can, however, build much more complicated structures. A structure canitself contain other structures by using a structure as a field type.

Here is a RECT structure which contains two POINTs named upperleft andlowerright:

  1. >>> class RECT(Structure):
  2. ...     _fields_ = [("upperleft", POINT),
  3. ...                 ("lowerright", POINT)]
  4. ...
  5. >>> rc = RECT(point)
  6. >>> print(rc.upperleft.x, rc.upperleft.y)
  7. 0 5
  8. >>> print(rc.lowerright.x, rc.lowerright.y)
  9. 0 0
  10. >>>

Nested structures can also be initialized in the constructor in several ways:

  1. >>> r = RECT(POINT(1, 2), POINT(3, 4))
  2. >>> r = RECT((1, 2), (3, 4))

Field descriptors can be retrieved from the class, they are usefulfor debugging because they can provide useful information:

  1. >>> print(POINT.x)
  2. <Field type=c_long, ofs=0, size=4>
  3. >>> print(POINT.y)
  4. <Field type=c_long, ofs=4, size=4>
  5. >>>

警告

ctypes does not support passing unions or structures with bit-fieldsto functions by value. While this may work on 32-bit x86, it's notguaranteed by the library to work in the general case. Unions andstructures with bit-fields should always be passed to functions by pointer.

Structure/union alignment and byte order

By default, Structure and Union fields are aligned in the same way the Ccompiler does it. It is possible to override this behavior be specifying apack class attribute in the subclass definition. This must be set to apositive integer and specifies the maximum alignment for the fields. This iswhat #pragma pack(n) also does in MSVC.

ctypes uses the native byte order for Structures and Unions. To buildstructures with non-native byte order, you can use one of theBigEndianStructure, LittleEndianStructure,BigEndianUnion, and LittleEndianUnion base classes. Theseclasses cannot contain pointer fields.

Bit fields in structures and unions

It is possible to create structures and unions containing bit fields. Bit fieldsare only possible for integer fields, the bit width is specified as the thirditem in the fields tuples:

  1. >>> class Int(Structure):
  2. ...     _fields_ = [("first_16", c_int, 16),
  3. ...                 ("second_16", c_int, 16)]
  4. ...
  5. >>> print(Int.first_16)
  6. <Field type=c_long, ofs=0:0, bits=16>
  7. >>> print(Int.second_16)
  8. <Field type=c_long, ofs=0:16, bits=16>
  9. >>>

Arrays

Arrays are sequences, containing a fixed number of instances of the same type.

The recommended way to create array types is by multiplying a data type with apositive integer:

  1. TenPointsArrayType = POINT * 10

Here is an example of a somewhat artificial data type, a structure containing 4POINTs among other stuff:

  1. >>> from ctypes import *
  2. >>> class POINT(Structure):
  3. ...     _fields_ = ("x", c_int), ("y", c_int)
  4. ...
  5. >>> class MyStruct(Structure):
  6. ...     _fields_ = [("a", c_int),
  7. ...                 ("b", c_float),
  8. ...                 ("point_array", POINT * 4)]
  9. >>>
  10. >>> print(len(MyStruct().point_array))
  11. 4
  12. >>>

Instances are created in the usual way, by calling the class:

  1. arr = TenPointsArrayType()
  2. for pt in arr:
  3.     print(pt.x, pt.y)

The above code print a series of 0 0 lines, because the array contents isinitialized to zeros.

Initializers of the correct type can also be specified:

  1. >>> from ctypes import *
  2. >>> TenIntegers = c_int * 10
  3. >>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
  4. >>> print(ii)
  5. <c_long_Array_10 object at 0x...>
  6. >>> for i in ii: print(i, end=" ")
  7. ...
  8. 1 2 3 4 5 6 7 8 9 10
  9. >>>

Pointers

Pointer instances are created by calling the pointer() function on actypes type:

  1. >>> from ctypes import *
  2. >>> i = c_int(42)
  3. >>> pi = pointer(i)
  4. >>>

Pointer instances have a contents attribute whichreturns the object to which the pointer points, the i object above:

  1. >>> pi.contents
  2. c_long(42)
  3. >>>

Note that ctypes does not have OOR (original object return), it constructs anew, equivalent object each time you retrieve an attribute:

  1. >>> pi.contents is i
  2. False
  3. >>> pi.contents is pi.contents
  4. False
  5. >>>

Assigning another c_int instance to the pointer's contents attributewould cause the pointer to point to the memory location where this is stored:

  1. >>> i = c_int(99)
  2. >>> pi.contents = i
  3. >>> pi.contents
  4. c_long(99)
  5. >>>

Pointer instances can also be indexed with integers:

  1. >>> pi[0]
  2. 99
  3. >>>

Assigning to an integer index changes the pointed to value:

  1. >>> print(i)
  2. c_long(99)
  3. >>> pi[0] = 22
  4. >>> print(i)
  5. c_long(22)
  6. >>>

It is also possible to use indexes different from 0, but you must know whatyou're doing, just as in C: You can access or change arbitrary memory locations.Generally you only use this feature if you receive a pointer from a C function,and you know that the pointer actually points to an array instead of a singleitem.

Behind the scenes, the pointer() function does more than simply createpointer instances, it has to create pointer types first. This is done with thePOINTER() function, which accepts any ctypes type, and returns anew type:

  1. >>> PI = POINTER(c_int)
  2. >>> PI
  3. <class 'ctypes.LP_c_long'>
  4. >>> PI(42)
  5. Traceback (most recent call last):
  6.   File "<stdin>", line 1, in <module>
  7. TypeError: expected c_long instead of int
  8. >>> PI(c_int(42))
  9. <ctypes.LP_c_long object at 0x...>
  10. >>>

Calling the pointer type without an argument creates a NULL pointer.NULL pointers have a False boolean value:

  1. >>> null_ptr = POINTER(c_int)()
  2. >>> print(bool(null_ptr))
  3. False
  4. >>>

ctypes checks for NULL when dereferencing pointers (but dereferencinginvalid non-NULL pointers would crash Python):

  1. >>> null_ptr[0]
  2. Traceback (most recent call last):
  3.     ....
  4. ValueError: NULL pointer access
  5. >>>
  6.  
  7. >>> null_ptr[0] = 1234
  8. Traceback (most recent call last):
  9.     ....
  10. ValueError: NULL pointer access
  11. >>>

Type conversions

Usually, ctypes does strict type checking. This means, if you havePOINTER(c_int) in the argtypes list of a function or as the type ofa member field in a structure definition, only instances of exactly the sametype are accepted. There are some exceptions to this rule, where ctypes acceptsother objects. For example, you can pass compatible array instances instead ofpointer types. So, for POINTER(c_int), ctypes accepts an array of c_int:

  1. >>> class Bar(Structure):
  2. ...     _fields_ = [("count", c_int), ("values", POINTER(c_int))]
  3. ...
  4. >>> bar = Bar()
  5. >>> bar.values = (c_int * 3)(1, 2, 3)
  6. >>> bar.count = 3
  7. >>> for i in range(bar.count):
  8. ...     print(bar.values[i])
  9. ...
  10. 1
  11. 2
  12. 3
  13. >>>

In addition, if a function argument is explicitly declared to be a pointer type(such as POINTER(c_int)) in argtypes, an object of the pointedtype (c_int in this case) can be passed to the function. ctypes will applythe required byref() conversion in this case automatically.

To set a POINTER type field to NULL, you can assign None:

  1. >>> bar.values = None
  2. >>>

Sometimes you have instances of incompatible types. In C, you can cast one typeinto another type. ctypes provides a cast() function which can beused in the same way. The Bar structure defined above acceptsPOINTER(c_int) pointers or c_int arrays for its values field,but not instances of other types:

  1. >>> bar.values = (c_byte * 4)()
  2. Traceback (most recent call last):
  3.   File "<stdin>", line 1, in <module>
  4. TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
  5. >>>

For these cases, the cast() function is handy.

The cast() function can be used to cast a ctypes instance into a pointerto a different ctypes data type. cast() takes two parameters, a ctypesobject that is or can be converted to a pointer of some kind, and a ctypespointer type. It returns an instance of the second argument, which referencesthe same memory block as the first argument:

  1. >>> a = (c_byte * 4)()
  2. >>> cast(a, POINTER(c_int))
  3. <ctypes.LP_c_long object at ...>
  4. >>>

So, cast() can be used to assign to the values field of Bar thestructure:

  1. >>> bar = Bar()
  2. >>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
  3. >>> print(bar.values[0])
  4. 0
  5. >>>

Incomplete Types

Incomplete Types are structures, unions or arrays whose members are not yetspecified. In C, they are specified by forward declarations, which are definedlater:

  1. struct cell; /* forward declaration */
  2.  
  3. struct cell {
  4.     char *name;
  5.     struct cell *next;
  6. };

The straightforward translation into ctypes code would be this, but it does notwork:

  1. >>> class cell(Structure):
  2. ...     _fields_ = [("name", c_char_p),
  3. ...                 ("next", POINTER(cell))]
  4. ...
  5. Traceback (most recent call last):
  6.   File "<stdin>", line 1, in <module>
  7.   File "<stdin>", line 2, in cell
  8. NameError: name 'cell' is not defined
  9. >>>

because the new class cell is not available in the class statement itself.In ctypes, we can define the cell class and set the fieldsattribute later, after the class statement:

  1. >>> from ctypes import *
  2. >>> class cell(Structure):
  3. ...     pass
  4. ...
  5. >>> cell._fields_ = [("name", c_char_p),
  6. ...                  ("next", POINTER(cell))]
  7. >>>

Lets try it. We create two instances of cell, and let them point to eachother, and finally follow the pointer chain a few times:

  1. >>> c1 = cell()
  2. >>> c1.name = "foo"
  3. >>> c2 = cell()
  4. >>> c2.name = "bar"
  5. >>> c1.next = pointer(c2)
  6. >>> c2.next = pointer(c1)
  7. >>> p = c1
  8. >>> for i in range(8):
  9. ...     print(p.name, end=" ")
  10. ...     p = p.next[0]
  11. ...
  12. foo bar foo bar foo bar foo bar
  13. >>>

Callback functions

ctypes allows creating C callable function pointers from Python callables.These are sometimes called callback functions.

First, you must create a class for the callback function. The class knows thecalling convention, the return type, and the number and types of arguments thisfunction will receive.

The CFUNCTYPE() factory function creates types for callback functionsusing the cdecl calling convention. On Windows, the WINFUNCTYPE()factory function creates types for callback functions using the stdcallcalling convention.

Both of these factory functions are called with the result type as firstargument, and the callback functions expected argument types as the remainingarguments.

I will present an example here which uses the standard C library'sqsort() function, that is used to sort items with the help of a callbackfunction. qsort() will be used to sort an array of integers:

  1. >>> IntArray5 = c_int * 5
  2. >>> ia = IntArray5(5, 1, 7, 33, 99)
  3. >>> qsort = libc.qsort
  4. >>> qsort.restype = None
  5. >>>

qsort() must be called with a pointer to the data to sort, the number ofitems in the data array, the size of one item, and a pointer to the comparisonfunction, the callback. The callback will then be called with two pointers toitems, and it must return a negative integer if the first item is smaller thanthe second, a zero if they are equal, and a positive integer otherwise.

So our callback function receives pointers to integers, and must return aninteger. First we create the type for the callback function:

  1. >>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
  2. >>>

To get started, here is a simple callback that shows the values it getspassed:

  1. >>> def py_cmp_func(a, b):
  2. ...     print("py_cmp_func", a[0], b[0])
  3. ...     return 0
  4. ...
  5. >>> cmp_func = CMPFUNC(py_cmp_func)
  6. >>>

The result:

  1. >>> qsort(ia, len(ia), sizeof(c_int), cmp_func)  
  2. py_cmp_func 5 1
  3. py_cmp_func 33 99
  4. py_cmp_func 7 33
  5. py_cmp_func 5 7
  6. py_cmp_func 1 7
  7. >>>

Now we can actually compare the two items and return a useful result:

  1. >>> def py_cmp_func(a, b):
  2. ...     print("py_cmp_func", a[0], b[0])
  3. ...     return a[0] - b[0]
  4. ...
  5. >>>
  6. >>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) 
  7. py_cmp_func 5 1
  8. py_cmp_func 33 99
  9. py_cmp_func 7 33
  10. py_cmp_func 1 7
  11. py_cmp_func 5 7
  12. >>>

As we can easily check, our array is sorted now:

  1. >>> for i in ia: print(i, end=" ")
  2. ...
  3. 1 5 7 33 99
  4. >>>

The function factories can be used as decorator factories, so we may as wellwrite:

  1. >>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
  2. ... def py_cmp_func(a, b):
  3. ...     print("py_cmp_func", a[0], b[0])
  4. ...     return a[0] - b[0]
  5. ...
  6. >>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)
  7. py_cmp_func 5 1
  8. py_cmp_func 33 99
  9. py_cmp_func 7 33
  10. py_cmp_func 1 7
  11. py_cmp_func 5 7
  12. >>>

注解

Make sure you keep references to CFUNCTYPE() objects as long as theyare used from C code. ctypes doesn't, and if you don't, they may begarbage collected, crashing your program when a callback is made.

Also, note that if the callback function is called in a thread createdoutside of Python's control (e.g. by the foreign code that calls thecallback), ctypes creates a new dummy Python thread on every invocation. Thisbehavior is correct for most purposes, but it means that values stored withthreading.local will not survive across different callbacks, even whenthose calls are made from the same C thread.

Accessing values exported from dlls

Some shared libraries not only export functions, they also export variables. Anexample in the Python library itself is the Py_OptimizeFlag, an integerset to 0, 1, or 2, depending on the -O or -OO flag given onstartup.

ctypes can access values like this with the indll() class methods ofthe type. _pythonapi is a predefined symbol giving access to the Python Capi:

  1. >>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
  2. >>> print(opt_flag)
  3. c_long(0)
  4. >>>

If the interpreter would have been started with -O, the sample wouldhave printed c_long(1), or c_long(2) if -OO would have beenspecified.

An extended example which also demonstrates the use of pointers accesses thePyImport_FrozenModules pointer exported by Python.

Quoting the docs for that value:

This pointer is initialized to point to an array of struct _frozenrecords, terminated by one whose members are all NULL or zero. When a frozenmodule is imported, it is searched in this table. Third-party code could playtricks with this to provide a dynamically created collection of frozen modules.

So manipulating this pointer could even prove useful. To restrict the examplesize, we show only how this table can be read with ctypes:

  1. >>> from ctypes import *
  2. >>>
  3. >>> class struct_frozen(Structure):
  4. ...     _fields_ = [("name", c_char_p),
  5. ...                 ("code", POINTER(c_ubyte)),
  6. ...                 ("size", c_int)]
  7. ...
  8. >>>

We have defined the struct _frozen data type, so we can get the pointerto the table:

  1. >>> FrozenTable = POINTER(struct_frozen)
  2. >>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
  3. >>>

Since table is a pointer to the array of struct_frozen records, wecan iterate over it, but we just have to make sure that our loop terminates,because pointers have no size. Sooner or later it would probably crash with anaccess violation or whatever, so it's better to break out of the loop when wehit the NULL entry:

  1. >>> for item in table:
  2. ...     if item.name is None:
  3. ...         break
  4. ...     print(item.name.decode("ascii"), item.size)
  5. ...
  6. _frozen_importlib 31764
  7. _frozen_importlib_external 41499
  8. __hello__ 161
  9. __phello__ -161
  10. __phello__.spam 161
  11. >>>

The fact that standard Python has a frozen module and a frozen package(indicated by the negative size member) is not well known, it is only used fortesting. Try it out with import hello for example.

Surprises

There are some edges in ctypes where you might expect something otherthan what actually happens.

Consider the following example:

  1. >>> from ctypes import *
  2. >>> class POINT(Structure):
  3. ...     _fields_ = ("x", c_int), ("y", c_int)
  4. ...
  5. >>> class RECT(Structure):
  6. ...     _fields_ = ("a", POINT), ("b", POINT)
  7. ...
  8. >>> p1 = POINT(1, 2)
  9. >>> p2 = POINT(3, 4)
  10. >>> rc = RECT(p1, p2)
  11. >>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
  12. 1 2 3 4
  13. >>> # now swap the two points
  14. >>> rc.a, rc.b = rc.b, rc.a
  15. >>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
  16. 3 4 3 4
  17. >>>

Hm. We certainly expected the last statement to print 3 4 1 2. Whathappened? Here are the steps of the rc.a, rc.b = rc.b, rc.a line above:

  1. >>> temp0, temp1 = rc.b, rc.a
  2. >>> rc.a = temp0
  3. >>> rc.b = temp1
  4. >>>

Note that temp0 and temp1 are objects still using the internal buffer ofthe rc object above. So executing rc.a = temp0 copies the buffercontents of temp0 into rc 's buffer. This, in turn, changes thecontents of temp1. So, the last assignment rc.b = temp1, doesn't havethe expected effect.

Keep in mind that retrieving sub-objects from Structure, Unions, and Arraysdoesn't copy the sub-object, instead it retrieves a wrapper object accessingthe root-object's underlying buffer.

Another example that may behave differently from what one would expect is this:

  1. >>> s = c_char_p()
  2. >>> s.value = b"abc def ghi"
  3. >>> s.value
  4. b'abc def ghi'
  5. >>> s.value is s.value
  6. False
  7. >>>

注解

Objects instantiated from c_char_p can only have their value set to bytesor integers.

Why is it printing False? ctypes instances are objects containing a memoryblock plus some descriptors accessing the contents of the memory.Storing a Python object in the memory block does not store the object itself,instead the contents of the object is stored. Accessing the contents againconstructs a new Python object each time!

Variable-sized data types

ctypes provides some support for variable-sized arrays and structures.

The resize() function can be used to resize the memory buffer of anexisting ctypes object. The function takes the object as first argument, andthe requested size in bytes as the second argument. The memory block cannot bemade smaller than the natural memory block specified by the objects type, aValueError is raised if this is tried:

  1. >>> short_array = (c_short * 4)()
  2. >>> print(sizeof(short_array))
  3. 8
  4. >>> resize(short_array, 4)
  5. Traceback (most recent call last):
  6.     ...
  7. ValueError: minimum size is 8
  8. >>> resize(short_array, 32)
  9. >>> sizeof(short_array)
  10. 32
  11. >>> sizeof(type(short_array))
  12. 8
  13. >>>

This is nice and fine, but how would one access the additional elementscontained in this array? Since the type still only knows about 4 elements, weget errors accessing other elements:

  1. >>> short_array[:]
  2. [0, 0, 0, 0]
  3. >>> short_array[7]
  4. Traceback (most recent call last):
  5.     ...
  6. IndexError: invalid index
  7. >>>

Another way to use variable-sized data types with ctypes is to use thedynamic nature of Python, and (re-)define the data type after the required sizeis already known, on a case by case basis.

ctypes reference

Finding shared libraries

When programming in a compiled language, shared libraries are accessed whencompiling/linking a program, and when the program is run.

The purpose of the find_library() function is to locate a library in a waysimilar to what the compiler or runtime loader does (on platforms with severalversions of a shared library the most recent should be loaded), while the ctypeslibrary loaders act like when a program is run, and call the runtime loaderdirectly.

The ctypes.util module provides a function which can help to determinethe library to load.

  • ctypes.util.findlibrary(_name)
  • Try to find a library and return a pathname. name is the library name withoutany prefix like lib, suffix like .so, .dylib or version number (thisis the form used for the posix linker option -l). If no library canbe found, returns None.

The exact functionality is system dependent.

On Linux, find_library() tries to run external programs(/sbin/ldconfig, gcc, objdump and ld) to find the library file.It returns the filename of the library file.

在 3.6 版更改: On Linux, the value of the environment variable LD_LIBRARY_PATH is usedwhen searching for libraries, if a library cannot be found by any other means.

Here are some examples:

  1. >>> from ctypes.util import find_library
  2. >>> find_library("m")
  3. 'libm.so.6'
  4. >>> find_library("c")
  5. 'libc.so.6'
  6. >>> find_library("bz2")
  7. 'libbz2.so.1.0'
  8. >>>

On OS X, find_library() tries several predefined naming schemes and pathsto locate the library, and returns a full pathname if successful:

  1. >>> from ctypes.util import find_library
  2. >>> find_library("c")
  3. '/usr/lib/libc.dylib'
  4. >>> find_library("m")
  5. '/usr/lib/libm.dylib'
  6. >>> find_library("bz2")
  7. '/usr/lib/libbz2.dylib'
  8. >>> find_library("AGL")
  9. '/System/Library/Frameworks/AGL.framework/AGL'
  10. >>>

On Windows, find_library() searches along the system search path, andreturns the full pathname, but since there is no predefined naming scheme a calllike find_library("c") will fail and return None.

If wrapping a shared library with ctypes, it may be better to determinethe shared library name at development time, and hardcode that into the wrappermodule instead of using find_library() to locate the library at runtime.

Loading shared libraries

There are several ways to load shared libraries into the Python process. Oneway is to instantiate one of the following classes:

  • class ctypes.CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)

  • Instances of this class represent loaded shared libraries. Functions in theselibraries use the standard C calling convention, and are assumed to returnint.

  • class ctypes.OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)

  • Windows only: Instances of this class represent loaded shared libraries,functions in these libraries use the stdcall calling convention, and areassumed to return the windows specific HRESULT code. HRESULTvalues contain information specifying whether the function call failed orsucceeded, together with additional error code. If the return value signals afailure, an OSError is automatically raised.

在 3.3 版更改: WindowsError used to be raised.

  • class ctypes.WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
  • Windows only: Instances of this class represent loaded shared libraries,functions in these libraries use the stdcall calling convention, and areassumed to return int by default.

On Windows CE only the standard calling convention is used, for convenience theWinDLL and OleDLL use the standard calling convention on thisplatform.

The Python global interpreter lock is released before calling anyfunction exported by these libraries, and reacquired afterwards.

  • class ctypes.PyDLL(name, mode=DEFAULT_MODE, handle=None)
  • Instances of this class behave like CDLL instances, except that thePython GIL is not released during the function call, and after the functionexecution the Python error flag is checked. If the error flag is set, a Pythonexception is raised.

Thus, this is only useful to call Python C api functions directly.

All these classes can be instantiated by calling them with at least oneargument, the pathname of the shared library. If you have an existing handle toan already loaded shared library, it can be passed as the handle namedparameter, otherwise the underlying platforms dlopen or LoadLibraryfunction is used to load the library into the process, and to get a handle toit.

The mode parameter can be used to specify how the library is loaded. Fordetails, consult the dlopen(3)) manpage. On Windows, mode isignored. On posix systems, RTLD_NOW is always added, and is notconfigurable.

The use_errno parameter, when set to true, enables a ctypes mechanism thatallows accessing the system errno error number in a safe way.ctypes maintains a thread-local copy of the systems errnovariable; if you call foreign functions created with use_errno=True then theerrno value before the function call is swapped with the ctypes privatecopy, the same happens immediately after the function call.

The function ctypes.get_errno() returns the value of the ctypes privatecopy, and the function ctypes.set_errno() changes the ctypes private copyto a new value and returns the former value.

The use_last_error parameter, when set to true, enables the same mechanism forthe Windows error code which is managed by the GetLastError() andSetLastError() Windows API functions; ctypes.get_last_error() andctypes.set_last_error() are used to request and change the ctypes privatecopy of the windows error code.

The winmode parameter is used on Windows to specify how the library is loaded(since mode is ignored). It takes any value that is valid for the Win32 APILoadLibraryEx flags parameter. When omitted, the default is to use the flagsthat result in the most secure DLL load to avoiding issues such as DLLhijacking. Passing the full path to the DLL is the safest way to ensure thecorrect library and dependencies are loaded.

在 3.8 版更改: Added winmode parameter.

  • ctypes.RTLD_GLOBAL

  • Flag to use as mode parameter. On platforms where this flag is not available,it is defined as the integer zero.

  • ctypes.RTLD_LOCAL

  • Flag to use as mode parameter. On platforms where this is not available, itis the same as RTLD_GLOBAL.

  • ctypes.DEFAULT_MODE

  • The default mode which is used to load shared libraries. On OSX 10.3, this isRTLD_GLOBAL, otherwise it is the same as RTLD_LOCAL.

Instances of these classes have no public methods. Functions exported by theshared library can be accessed as attributes or by index. Please note thataccessing the function through an attribute caches the result and thereforeaccessing it repeatedly returns the same object each time. On the other hand,accessing it through an index returns a new object each time:

  1. >>> from ctypes import CDLL
  2. >>> libc = CDLL("libc.so.6")  # On Linux
  3. >>> libc.time == libc.time
  4. True
  5. >>> libc['time'] == libc['time']
  6. False

The following public attributes are available, their name starts with anunderscore to not clash with exported function names:

  • PyDLL._handle

  • The system handle used to access the library.

  • PyDLL._name

  • The name of the library passed in the constructor.

Shared libraries can also be loaded by using one of the prefabricated objects,which are instances of the LibraryLoader class, either by calling theLoadLibrary() method, or by retrieving the library as attribute of theloader instance.

  • class ctypes.LibraryLoader(dlltype)
  • Class which loads shared libraries. dlltype should be one of theCDLL, PyDLL, WinDLL, or OleDLL types.

getattr() has special behavior: It allows loading a shared library byaccessing it as attribute of a library loader instance. The result is cached,so repeated attribute accesses return the same library each time.

  • LoadLibrary(name)
  • Load a shared library into the process and return it. This method alwaysreturns a new instance of the library.

These prefabricated library loaders are available:

  • ctypes.cdll

  • Creates CDLL instances.

  • ctypes.windll

  • 仅Windows中: 创建 WinDLL 实例.

  • ctypes.oledll

  • 仅Windows中: 创建 OleDLL 实例。

  • ctypes.pydll

  • 创建 PyDLL 实例。

For accessing the C Python api directly, a ready-to-use Python shared libraryobject is available:

  • ctypes.pythonapi
  • An instance of PyDLL that exposes Python C API functions asattributes. Note that all these functions are assumed to return Cint, which is of course not always the truth, so you have to assignthe correct restype attribute to use these functions.

Loading a library through any of these objects raises anauditing event ctypes.dlopen with string argumentname, the name used to load the library.

Accessing a function on a loaded library raises an auditing eventctypes.dlsym with arguments library (the library object) and name(the symbol's name as a string or integer).

In cases when only the library handle is available rather than the object,accessing a function raises an auditing event ctypes.dlsym/handle witharguments handle (the raw library handle) and name.

Foreign functions

As explained in the previous section, foreign functions can be accessed asattributes of loaded shared libraries. The function objects created in this wayby default accept any number of arguments, accept any ctypes data instances asarguments, and return the default result type specified by the library loader.They are instances of a private class:

  • class ctypes._FuncPtr
  • Base class for C callable foreign functions.

Instances of foreign functions are also C compatible data types; theyrepresent C function pointers.

This behavior can be customized by assigning to special attributes of theforeign function object.

  • restype
  • Assign a ctypes type to specify the result type of the foreign function.Use None for void, a function not returning anything.

It is possible to assign a callable Python object that is not a ctypestype, in this case the function is assumed to return a C int, andthe callable will be called with this integer, allowing furtherprocessing or error checking. Using this is deprecated, for more flexiblepost processing or error checking use a ctypes data type asrestype and assign a callable to the errcheck attribute.

  • argtypes
  • Assign a tuple of ctypes types to specify the argument types that thefunction accepts. Functions using the stdcall calling convention canonly be called with the same number of arguments as the length of thistuple; functions using the C calling convention accept additional,unspecified arguments as well.

When a foreign function is called, each actual argument is passed to thefrom_param() class method of the items in the argtypestuple, this method allows adapting the actual argument to an object thatthe foreign function accepts. For example, a c_char_p item inthe argtypes tuple will convert a string passed as argument intoa bytes object using ctypes conversion rules.

New: It is now possible to put items in argtypes which are not ctypestypes, but each item must have a from_param() method which returns avalue usable as argument (integer, string, ctypes instance). This allowsdefining adapters that can adapt custom objects as function parameters.

  • errcheck

  • Assign a Python function or another callable to this attribute. Thecallable will be called with three or more arguments:

    • callable(result, func, arguments)
    • result is what the foreign function returns, as specified by therestype attribute.

func is the foreign function object itself, this allows reusing thesame callable object to check or post process the results of severalfunctions.

arguments is a tuple containing the parameters originally passed tothe function call, this allows specializing the behavior on thearguments used.

The object that this function returns will be returned from theforeign function call, but it can also check the result valueand raise an exception if the foreign function call failed.

  • exception ctypes.ArgumentError
  • This exception is raised when a foreign function call cannot convert one of thepassed arguments.

On Windows, when a foreign function call raises a system exception (forexample, due to an access violation), it will be captured and replaced witha suitable Python exception. Further, an auditing eventctypes.seh_exception with argument code will be raised, allowing anaudit hook to replace the exception with its own.

Some ways to invoke foreign function calls may raise an auditing eventctypes.call_function with arguments function pointer and arguments.

Function prototypes

Foreign functions can also be created by instantiating function prototypes.Function prototypes are similar to function prototypes in C; they describe afunction (return type, argument types, calling convention) without defining animplementation. The factory functions must be called with the desired resulttype and the argument types of the function, and can be used as decoratorfactories, and as such, be applied to functions through the @wrapper syntax.See Callback functions for examples.

  • ctypes.CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

  • The returned function prototype creates functions that use the standard Ccalling convention. The function will release the GIL during the call. Ifuse_errno is set to true, the ctypes private copy of the systemerrno variable is exchanged with the real errno value beforeand after the call; use_last_error does the same for the Windows errorcode.

  • ctypes.WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

  • Windows only: The returned function prototype creates functions that use thestdcall calling convention, except on Windows CE whereWINFUNCTYPE() is the same as CFUNCTYPE(). The function willrelease the GIL during the call. use_errno and use_last_error have thesame meaning as above.

  • ctypes.PYFUNCTYPE(restype, *argtypes)

  • The returned function prototype creates functions that use the Python callingconvention. The function will not release the GIL during the call.

Function prototypes created by these factory functions can be instantiated indifferent ways, depending on the type and number of the parameters in the call:

prototype(address)

Returns a foreign function at the specified address which must be an integer.

prototype(callable)

Create a C callable function (a callback function) from a Python callable.

prototype(func_spec[, paramflags])

Returns a foreign function exported by a shared library. func_spec mustbe a 2-tuple (name_or_ordinal, library). The first item is the name ofthe exported function as string, or the ordinal of the exported functionas small integer. The second item is the shared library instance.

prototype(vtbl_index, name[, paramflags[, iid]])

Returns a foreign function that will call a COM method. vtbl_index isthe index into the virtual function table, a small non-negativeinteger. name is name of the COM method. iid is an optional pointer tothe interface identifier which is used in extended error reporting.

COM methods use a special calling convention: They require a pointer tothe COM interface as first argument, in addition to those parameters thatare specified in the argtypes tuple.

The optional paramflags parameter creates foreign function wrappers with muchmore functionality than the features described above.

paramflags must be a tuple of the same length as argtypes.

Each item in this tuple contains further information about a parameter, it mustbe a tuple containing one, two, or three items.

The first item is an integer containing a combination of directionflags for the parameter:

1

Specifies an input parameter to the function.

2

Output parameter. The foreign function fills in a value.

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 third item is the default value for this parameter.

This example demonstrates how to wrap the Windows MessageBoxW function sothat it supports default parameters and named arguments. The C declaration fromthe windows header file is this:

  1. WINUSERAPI int WINAPI
  2. MessageBoxW(
  3.     HWND hWnd,
  4.     LPCWSTR lpText,
  5.     LPCWSTR lpCaption,
  6.     UINT uType);

Here is the wrapping with ctypes:

  1. >>> from ctypes import c_int, WINFUNCTYPE, windll
  2. >>> from ctypes.wintypes import HWND, LPCWSTR, UINT
  3. >>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)
  4. >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", "Hello from ctypes"), (1, "flags", 0)
  5. >>> MessageBox = prototype(("MessageBoxW", windll.user32), paramflags)

The MessageBox foreign function can now be called in these ways:

  1. >>> MessageBox()
  2. >>> MessageBox(text="Spam, spam, spam")
  3. >>> MessageBox(flags=2, text="foo bar")

A second example demonstrates output parameters. The win32 GetWindowRectfunction retrieves the dimensions of a specified window by copying them intoRECT structure that the caller has to supply. Here is the C declaration:

  1. WINUSERAPI BOOL WINAPI
  2. GetWindowRect(
  3.      HWND hWnd,
  4.      LPRECT lpRect);

Here is the wrapping with ctypes:

  1. >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
  2. >>> from ctypes.wintypes import BOOL, HWND, RECT
  3. >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
  4. >>> paramflags = (1, "hwnd"), (2, "lprect")
  5. >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
  6. >>>

Functions with output parameters will automatically return the output parametervalue if there is a single one, or a tuple containing the output parametervalues when there are more than one, so the GetWindowRect function now returns aRECT instance, when called.

Output parameters can be combined with the errcheck protocol to dofurther output processing and error checking. The win32 GetWindowRect apifunction returns a BOOL to signal success or failure, so this function coulddo the error checking, and raises an exception when the api call failed:

  1. >>> def errcheck(result, func, args):
  2. ...     if not result:
  3. ...         raise WinError()
  4. ...     return args
  5. ...
  6. >>> GetWindowRect.errcheck = errcheck
  7. >>>

If the errcheck function returns the argument tuple it receivesunchanged, ctypes continues the normal processing it does on the outputparameters. If you want to return a tuple of window coordinates instead of aRECT instance, you can retrieve the fields in the function and return theminstead, the normal processing will no longer take place:

  1. >>> def errcheck(result, func, args):
  2. ...     if not result:
  3. ...         raise WinError()
  4. ...     rc = args[1]
  5. ...     return rc.left, rc.top, rc.bottom, rc.right
  6. ...
  7. >>> GetWindowRect.errcheck = errcheck
  8. >>>

Utility functions

  • ctypes.addressof(obj)
  • Returns the address of the memory buffer as integer. obj must be aninstance of a ctypes type.

Raises an auditing event ctypes.addressof with argument obj.

  • ctypes.alignment(obj_or_type)

  • Returns the alignment requirements of a ctypes type. obj_or_type must be actypes type or instance.

  • ctypes.byref(obj[, offset])

  • Returns a light-weight pointer to obj, which must be an instance of actypes type. offset defaults to zero, and must be an integer that will beadded to the internal pointer value.

byref(obj, offset) corresponds to this C code:

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

  • ctypes.cast(obj, type)

  • This function is similar to the cast operator in C. It returns a new instanceof type which points to the same memory block as obj. type must be apointer type, and obj must be an object that can be interpreted as apointer.

  • ctypes.createstring_buffer(_init_or_size, size=None)

  • This function creates a mutable character buffer. The returned object is actypes array of c_char.

init_or_size must be an integer which specifies the size of the array, or abytes object which will be used to initialize the array items.

If a bytes object is specified as first argument, the buffer is made one itemlarger than its length so that the last element in the array is a NULtermination character. An integer can be passed as second argument which allowsspecifying the size of the array if the length of the bytes should not be used.

Raises an auditing event ctypes.create_string_buffer with arguments init, size.

  • ctypes.createunicode_buffer(_init_or_size, size=None)
  • This function creates a mutable unicode character buffer. The returned object isa ctypes array of c_wchar.

init_or_size must be an integer which specifies the size of the array, or astring which will be used to initialize the array items.

If a string is specified as first argument, the buffer is made one itemlarger than the length of the string so that the last element in the array is aNUL termination character. An integer can be passed as second argument whichallows specifying the size of the array if the length of the string should notbe used.

Raises an auditing event ctypes.create_unicode_buffer with arguments init, size.

  • ctypes.DllCanUnloadNow()

  • Windows only: This function is a hook which allows implementing in-processCOM servers with ctypes. It is called from the DllCanUnloadNow function thatthe _ctypes extension dll exports.

  • ctypes.DllGetClassObject()

  • Windows only: This function is a hook which allows implementing in-processCOM servers with ctypes. It is called from the DllGetClassObject functionthat the _ctypes extension dll exports.

  • ctypes.util.findlibrary(_name)

  • Try to find a library and return a pathname. name is the library namewithout any prefix like lib, suffix like .so, .dylib or versionnumber (this is the form used for the posix linker option -l). Ifno library can be found, returns None.

The exact functionality is system dependent.

  • ctypes.util.find_msvcrt()
  • Windows only: return the filename of the VC runtime library used by Python,and by the extension modules. If the name of the library cannot bedetermined, None is returned.

If you need to free memory, for example, allocated by an extension modulewith a call to the free(void *), it is important that you use thefunction in the same library that allocated the memory.

  • ctypes.FormatError([code])

  • Windows only: Returns a textual description of the error code code. If noerror code is specified, the last error code is used by calling the Windowsapi function GetLastError.

  • ctypes.GetLastError()

  • Windows only: Returns the last error code set by Windows in the calling thread.This function calls the Windows GetLastError() function directly,it does not return the ctypes-private copy of the error code.

  • ctypes.get_errno()

  • Returns the current value of the ctypes-private copy of the systemerrno variable in the calling thread.

Raises an auditing event ctypes.get_errno with no arguments.

  • ctypes.get_last_error()
  • Windows only: returns the current value of the ctypes-private copy of the systemLastError variable in the calling thread.

Raises an auditing event ctypes.get_last_error with no arguments.

  • ctypes.memmove(dst, src, count)

  • Same as the standard C memmove library function: copies count bytes fromsrc to dst. dst and src must be integers or ctypes instances that canbe converted to pointers.

  • ctypes.memset(dst, c, count)

  • Same as the standard C memset library function: fills the memory block ataddress dst with count bytes of value c. dst must be an integerspecifying an address, or a ctypes instance.

  • ctypes.POINTER(type)

  • This factory function creates and returns a new ctypes pointer type. Pointertypes are cached and reused internally, so calling this function repeatedly ischeap. type must be a ctypes type.

  • ctypes.pointer(obj)

  • This function creates a new pointer instance, pointing to obj. The returnedobject is of the type POINTER(type(obj)).

Note: If you just want to pass a pointer to an object to a foreign functioncall, you should use byref(obj) which is much faster.

  • ctypes.resize(obj, size)

  • This function resizes the internal memory buffer of obj, which must be aninstance of a ctypes type. It is not possible to make the buffer smallerthan the native size of the objects type, as given by sizeof(type(obj)),but it is possible to enlarge the buffer.

  • ctypes.seterrno(_value)

  • Set the current value of the ctypes-private copy of the system errnovariable in the calling thread to value and return the previous value.

Raises an auditing event ctypes.set_errno with argument errno.

  • ctypes.setlast_error(_value)
  • Windows only: set the current value of the ctypes-private copy of the systemLastError variable in the calling thread to value and return theprevious value.

Raises an auditing event ctypes.set_last_error with argument error.

  • ctypes.sizeof(obj_or_type)

  • Returns the size in bytes of a ctypes type or instance memory buffer.Does the same as the C sizeof operator.

  • ctypes.stringat(_address, size=-1)

  • This function returns the C string starting at memory address address as a bytesobject. If size is specified, it is used as size, otherwise the string is assumedto be zero-terminated.

Raises an auditing event ctypes.string_at with arguments address, size.

  • ctypes.WinError(code=None, descr=None)
  • Windows only: this function is probably the worst-named thing in ctypes. Itcreates an instance of OSError. If code is not specified,GetLastError is called to determine the error code. If descr is notspecified, FormatError() is called to get a textual description of theerror.

在 3.3 版更改: An instance of WindowsError used to be created.

  • ctypes.wstringat(_address, size=-1)
  • This function returns the wide character string starting at memory addressaddress as a string. If size is specified, it is used as the number ofcharacters of the string, otherwise the string is assumed to bezero-terminated.

Raises an auditing event ctypes.wstring_at with arguments address, size.

Data types

  • class ctypes._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 thathold C compatible data; the address of the memory block is returned by theaddressof() helper function. Another instance variable is exposed as_objects; this contains other Python objects that need to be keptalive in case the memory block contains pointers.

Common methods of ctypes data types, these are all class methods (to beexact, they are methods of the metaclass):

  • frombuffer(_source[, offset])
  • This method returns a ctypes instance that shares the buffer of thesource object. The source object must support the writeable bufferinterface. The optional offset parameter specifies an offset into thesource buffer in bytes; the default is zero. If the source buffer is notlarge enough a ValueError is raised.

Raises an auditing event ctypes.cdata/buffer with arguments pointer, size, offset.

  • frombuffer_copy(_source[, offset])
  • This method creates a ctypes instance, copying the buffer from thesource object buffer which must be readable. The optional _offset_parameter specifies an offset into the source buffer in bytes; the defaultis zero. If the source buffer is not large enough a ValueError israised.

Raises an auditing event ctypes.cdata/buffer with arguments pointer, size, offset.

  • fromaddress(_address)
  • This method returns a ctypes type instance using the memory specified byaddress which must be an integer.

This method, and others that indirectly call this method, raises anauditing event ctypes.cdata with argumentaddress.

  • fromparam(_obj)
  • This method adapts obj to a ctypes type. It is called with the actualobject used in a foreign function call when the type is present in theforeign function's argtypes tuple; it must return an object thatcan be used as a function call parameter.

All ctypes data types have a default implementation of this classmethodthat normally returns obj if that is an instance of the type. Sometypes accept other objects as well.

  • indll(_library, name)
  • This method returns a ctypes type instance exported by a sharedlibrary. name is the name of the symbol that exports the data, _library_is the loaded shared library.

Common instance variables of ctypes data types:

  • b_base

  • Sometimes ctypes data instances do not own the memory block they contain,instead they share part of the memory block of a base object. Theb_base read-only member is the root ctypes object that owns thememory block.

  • b_needsfree

  • This read-only variable is true when the ctypes data instance hasallocated the memory block itself, false otherwise.

  • _objects

  • This member is either None or a dictionary containing Python objectsthat need to be kept alive so that the memory block contents is keptvalid. This object is only exposed for debugging; never modify thecontents of this dictionary.

基础数据类型

  • class ctypes._SimpleCData
  • This non-public class is the base class of all fundamental ctypes datatypes. It is mentioned here because it contains the common attributes of thefundamental ctypes data types. _SimpleCData is a subclass of_CData, so it inherits their methods and attributes. ctypes datatypes that are not and do not contain pointers can now be pickled.

Instances have a single attribute:

  • value
  • This attribute contains the actual value of the instance. For integer andpointer types, it is an integer, for character types, it is a singlecharacter bytes object or string, for character pointer types it is aPython bytes object or string.

When the value attribute is retrieved from a ctypes instance, usuallya new object is returned each time. ctypes does not implementoriginal object return, always a new object is constructed. The same istrue for all other ctypes object instances.

Fundamental data types, when returned as foreign function call results, or, forexample, by retrieving structure field members or array items, are transparentlyconverted to native Python types. In other words, if a foreign function has arestype of c_char_p, you will always receive a Python bytesobject, not a c_char_p instance.

Subclasses of fundamental data types do not inherit this behavior. So, if aforeign functions restype is a subclass of c_void_p, you willreceive an instance of this subclass from the function call. Of course, you canget the value of the pointer by accessing the value attribute.

These are the fundamental ctypes data types:

  • class ctypes.c_byte

  • Represents the C signed char datatype, and interprets the value assmall integer. The constructor accepts an optional integer initializer; nooverflow checking is done.

  • class ctypes.c_char

  • Represents the C char datatype, and interprets the value as a singlecharacter. The constructor accepts an optional string initializer, thelength of the string must be exactly one character.

  • class ctypes.c_char_p

  • Represents the C char * datatype when it points to a zero-terminatedstring. For a general character pointer that may also point to binary data,POINTER(c_char) must be used. The constructor accepts an integeraddress, or a bytes object.

  • class ctypes.c_double

  • Represents the C double datatype. The constructor accepts anoptional float initializer.

  • class ctypes.c_longdouble

  • Represents the C long double datatype. The constructor accepts anoptional float initializer. On platforms where sizeof(long double) ==sizeof(double) it is an alias to c_double.

  • class ctypes.c_float

  • Represents the C float datatype. The constructor accepts anoptional float initializer.

  • class ctypes.c_int

  • Represents the C signed int datatype. The constructor accepts anoptional integer initializer; no overflow checking is done. On platformswhere sizeof(int) == sizeof(long) it is an alias to c_long.

  • class ctypes.c_int8

  • Represents the C 8-bit signed int datatype. Usually an alias forc_byte.

  • class ctypes.c_int16

  • Represents the C 16-bit signed int datatype. Usually an alias forc_short.

  • class ctypes.c_int32

  • Represents the C 32-bit signed int datatype. Usually an alias forc_int.

  • class ctypes.c_int64

  • Represents the C 64-bit signed int datatype. Usually an alias forc_longlong.

  • class ctypes.c_long

  • Represents the C signed long datatype. The constructor accepts anoptional integer initializer; no overflow checking is done.

  • class ctypes.c_longlong

  • Represents the C signed long long datatype. The constructor acceptsan optional integer initializer; no overflow checking is done.

  • class ctypes.c_short

  • Represents the C signed short datatype. The constructor accepts anoptional integer initializer; no overflow checking is done.

  • class ctypes.c_size_t

  • Represents the C size_t datatype.

  • class ctypes.c_ssize_t

  • Represents the C ssize_t datatype.

3.2 新版功能.

  • class ctypes.c_ubyte

  • Represents the C unsigned char datatype, it interprets the value assmall integer. The constructor accepts an optional integer initializer; nooverflow checking is done.

  • class ctypes.c_uint

  • Represents the C unsigned int datatype. The constructor accepts anoptional integer initializer; no overflow checking is done. On platformswhere sizeof(int) == sizeof(long) it is an alias for c_ulong.

  • class ctypes.c_uint8

  • Represents the C 8-bit unsigned int datatype. Usually an alias forc_ubyte.

  • class ctypes.c_uint16

  • Represents the C 16-bit unsigned int datatype. Usually an alias forc_ushort.

  • class ctypes.c_uint32

  • Represents the C 32-bit unsigned int datatype. Usually an alias forc_uint.

  • class ctypes.c_uint64

  • Represents the C 64-bit unsigned int datatype. Usually an alias forc_ulonglong.

  • class ctypes.c_ulong

  • Represents the C unsigned long datatype. The constructor accepts anoptional integer initializer; no overflow checking is done.

  • class ctypes.c_ulonglong

  • Represents the C unsigned long long datatype. The constructoraccepts an optional integer initializer; no overflow checking is done.

  • class ctypes.c_ushort

  • Represents the C unsigned short datatype. The constructor acceptsan optional integer initializer; no overflow checking is done.

  • class ctypes.c_void_p

  • Represents the C void * type. The value is represented as integer.The constructor accepts an optional integer initializer.

  • class ctypes.c_wchar

  • Represents the C wchar_t datatype, and interprets the value as asingle character unicode string. The constructor accepts an optional stringinitializer, the length of the string must be exactly one character.

  • class ctypes.c_wchar_p

  • Represents the C wchar_t * datatype, which must be a pointer to azero-terminated wide character string. The constructor accepts an integeraddress, or a string.

  • class ctypes.c_bool

  • Represent the C bool datatype (more accurately, _Bool fromC99). Its value can be True or False, and the constructor accepts any objectthat has a truth value.

  • class ctypes.HRESULT

  • Windows only: Represents a HRESULT value, which contains success orerror information for a function or method call.

  • class ctypes.py_object

  • Represents the C PyObject * datatype. Calling this without anargument creates a NULL PyObject * pointer.

The ctypes.wintypes module provides quite some other Windows specificdata types, for example HWND, WPARAM, or DWORD. Someuseful structures like MSG or RECT are also defined.

Structured data types

  • class ctypes.Union(*args, **kw)

  • Abstract base class for unions in native byte order.

  • class ctypes.BigEndianStructure(*args, **kw)

  • Abstract base class for structures in big endian byte order.

  • class ctypes.LittleEndianStructure(*args, **kw)

  • Abstract base class for structures in little endian byte order.

Structures with non-native byte order cannot contain pointer type fields, or anyother data types containing pointer type fields.

  • class ctypes.Structure(*args, **kw)
  • Abstract base class for structures in native byte order.

Concrete structure and union types must be created by subclassing one of thesetypes, and at least define a fields class variable. ctypes willcreate descriptors which allow reading and writing the fields by directattribute accesses. These are the

  • fields
  • A sequence defining the structure fields. The items must be 2-tuples or3-tuples. The first item is the name of the field, the second itemspecifies the type of the field; it can be any ctypes data type.

For integer type fields like c_int, a third optional item can begiven. It must be a small positive integer defining the bit width of thefield.

Field names must be unique within one structure or union. This is notchecked, only one field can be accessed when names are repeated.

It is possible to define the fields class variable after theclass statement that defines the Structure subclass, this allows creatingdata types that directly or indirectly reference themselves:

  1. class List(Structure):
  2.     pass
  3. List._fields_ = [("pnext", POINTER(List)),
  4.                  ...
  5.                 ]

The fields class variable must, however, be defined before thetype is first used (an instance is created, sizeof() is called on it,and so on). Later assignments to the fields class variable willraise an AttributeError.

It is possible to define sub-subclasses of structure types, they inheritthe fields of the base class plus the fields defined in thesub-subclass, if any.

  • pack

  • An optional small integer that allows overriding the alignment ofstructure fields in the instance. pack must already be definedwhen fields is assigned, otherwise it will have no effect.

  • anonymous

  • An optional sequence that lists the names of unnamed (anonymous) fields.anonymous must be already defined when fields isassigned, otherwise it will have no effect.

The fields listed in this variable must be structure or union type fields.ctypes will create descriptors in the structure type that allowsaccessing the nested fields directly, without the need to create thestructure or union field.

Here is an example type (Windows):

  1. class _U(Union):
  2.     _fields_ = [("lptdesc", POINTER(TYPEDESC)),
  3.                 ("lpadesc", POINTER(ARRAYDESC)),
  4.                 ("hreftype", HREFTYPE)]
  5.  
  6. class TYPEDESC(Structure):
  7.     _anonymous_ = ("u",)
  8.     _fields_ = [("u", _U),
  9.                 ("vt", VARTYPE)]

The TYPEDESC structure describes a COM data type, the vt fieldspecifies which one of the union fields is valid. Since the u fieldis defined as anonymous field, it is now possible to access the membersdirectly off the TYPEDESC instance. td.lptdesc and td.u.lptdescare equivalent, but the former is faster since it does not need to createa temporary union instance:

  1. td = TYPEDESC()
  2. td.vt = VT_PTR
  3. td.lptdesc = POINTER(some_type)
  4. td.u.lptdesc = POINTER(some_type)

It is possible to define sub-subclasses of structures, they inherit thefields of the base class. If the subclass definition has a separatefields variable, the fields specified in this are appended to thefields of the base class.

Structure and union constructors accept both positional and keywordarguments. Positional arguments are used to initialize member fields in thesame order as they are appear in fields. Keyword arguments in theconstructor are interpreted as attribute assignments, so they will initializefields with the same name, or create new attributes for names notpresent in fields.

Arrays and pointers

  • class ctypes.Array(*args)
  • Abstract base class for arrays.

The recommended way to create concrete array types is by multiplying anyctypes data type with a positive integer. Alternatively, you can subclassthis type and define length and type class variables.Array elements can be read and written using standardsubscript and slice accesses; for slice reads, the resulting object isnot itself an Array.

  • length

  • A positive integer specifying the number of elements in the array.Out-of-range subscripts result in an IndexError. Will bereturned by len().

  • type

  • Specifies the type of each element in the array.

Array subclass constructors accept positional arguments, used toinitialize the elements in order.

  • class ctypes._Pointer
  • Private, abstract base class for pointers.

Concrete pointer types are created by calling POINTER() with thetype that will be pointed to; this is done automatically bypointer().

If a pointer points to an array, its elements can be read andwritten using standard subscript and slice accesses. Pointer objectshave no size, so len() will raise TypeError. Negativesubscripts will read from the memory before the pointer (as in C), andout-of-range subscripts will probably crash with an access violation (ifyou're lucky).

  • type

  • Specifies the type pointed to.

  • contents

  • Returns the object to which to pointer points. Assigning to thisattribute changes the pointer to point to the assigned object.