Extending Python Using Ctypes

James Teh

NetBox Blue Pty Ltd

What Is ctypes?

• Advanced ffi (foreign function interface) package for Python
• Python 2.3 and higher; included with Python 2.5
• Provides C compatible data types
• Allows to call functions in dlls/shared libraries
• Can be used to wrap these libraries in pure Python
• Even allows for C callback functions in pure Python
• http://python.net/crew/theller/ctypes/

Getting Started

• Accessing the C standard library:
  • In Windows:
    

    >>> from ctypes import *
    >>> libc = cdll.msvcrt
    

    Just access libraries as attributes of cdll
  • In Linux:
    

    >>> from ctypes import *
    >>> libc = CDLL("libc.so.6")
    

    Must specify full filename, so can't use attribute access
• Hello world:
  

  >>> libc.printf("Hello, world!\n")
  Hello, world!
  14
  

Simple Data Types

• ctypes has simple data types corresponding to those in C:
• c_byte, c_int/c_long, c_double, c_float, c_char
• Also c_ubyte, c_uint/c_ulong for unsigned data
• You can construct them with or without a value:
  

  >>> c_int()
  c_long(0)
  >>> c_int(10)
  c_long(10)
  >>> c_char()
  c_char('\x00')
  

• You can change their value:
  

  >>> b = c_ubyte(); b.value
  0
  >>> b.value -= 1; b
  c_ubyte(255)
  

Calling Functions

• You simply access functions as attributes of the dll:
  

  >>> libc.rand
  <_FuncPtr object at 0xb7e02984>
  >>> libc.rand()
  719885386
  

• ctypes assumes the return type is int by default
• ctypes converts Python int, long and str objects as input arguments into appropriate C types:
  

  >>> libc.abs(-10)
  10
  >>> libc.strlen('penguins')
  8
  

• You can of course pass ctypes types as parameters:
  

  >>> libm.fabs(c_double(-5.5))
  8
  

>>> c_int.in_dll(libc, 'errno')
c_long(0)

Specifying Argument and Return Types

• Bugger! fabs() returns a double, so this is the wrong return type!
• You can specify the return type with the restype attribute:
  

  >>> libm.fabs.restype = c_double
  >>> libm.fabs(c_double(-5.5))
  5.5
  

• And you can specify the argument types with argtypes:
  

  >>> libm.fabs.argtypes = (c_double,)
  >>> libm.fabs(-5.5)
  5.5
  

Pointers

• You can obtain a pointer to a ctypes instance:
  

  >>> i = c_int(42); i
  c_long(42)
  >>> pi = pointer(i); pi
  <ctypes.LP_c_long object at 0x009D98A0>
  

• You can access and change the object to which the pointer points:
  

  >>> pi.contents
  c_long(42)
  >>> i = c_int(5); pi.contents = i; pi.contents
  c_long(5)
  

• You can access and change the value of the target object directly by indexing:
  

  >>> pi[0]
  5
  >>> pi[0] = 10; pi.contents
  c_long(10)
  >>> i.value
  10
  >>> i.value = 15; pi[0]
  15
  

• Can access indexes other than 0 as in C; e.g. C function returning a pointer to an array

Pointers

• pointer() has to create pointer types first
• Can create pointer types ourselves:
  

  >>> intp = POINTER(c_int); intp
  <class 'ctypes.LP_c_long'>
  >>> pi = intp(i); pi
  <ctypes.LP_c_long object at 0x009D99E0>
  

• You can pass pointers to C functions:
  

  >>> libc.sscanf('9', '%d', pi)
  1
  >>> pi.contents
  c_long(9)
  

• Easier and more efficient to use byref() if you don't need the pointer object:
  

  >>> libc.sscanf('3', '%d', byref(i))
  1
  >>> i.value
  3
  

Arrays

• You create arrays by multiplying a type by a positive integer:
  

  >>> int3 = c_int * 3; int3
  <class 'ctypes._endian.c_long_Array_3'>
  >>> i3 = int3(); [i for i in i3]
  [0, 0, 0]
  >>> i3 = int3(1, 2, 3); [i for i in i3]
  [1, 2, 3]
  

• Example with sprintf:
  

  >>> s = (c_char * 9)()
  >>> libc.sprintf(s, '%dmonkeys', 5)
  >>> "".join(s)
  '5monkeys\x00'
  

• char arrays also have value attribute which yields the string up to NULL and raw attribute to access the raw buffer
• Easier to create char arrays with create_string_buffer(len)

Returned Pointers

• Functions can return pointers:
  

  >>> libc.tmpnam = POINTER(c_char)
  >>> s = libc.tmpnam(None); s
  <ctypes.LP_c_char object at 0xb7d2f8e4>
  >>> s[0:5]
  '/tmp/'
  

• c_char_p is a much smarter string pointer:
  

  >>> libc.tmpnam.restype = c_char_p
  >>> libc.tmpnam(None)
  '/tmp/filevZ6H67'
  

Error Handling

• errcheck attribute can be used to do error checking:
  

  >>> def errcheck(res, func, args):
  ...   if not res:
  ...     raise IOError('Error opening file')
  ...   return res
  ...
  >>> libc.fopen.errcheck = errcheck
  >>> libc.fopen('notexist', 'r')
  Traceback (most recent call last):
    ...
  IOError: Error opening file
  >>> libc.fopen('/bin/ls', 'r')
  135958576