@@ -1111,13 +1110,83 @@ by some specifications, so it's still available as
The \module{ctypes} package, written by Thomas Heller, has been added
to the standard library. \module{ctypes} lets you call arbitrary functions
in shared libraries or DLLs.
in shared libraries or DLLs. Long-time users may remember the \module{dl} module, which
provides functions for loading shared libraries and calling functions in them. The \module{ctypes} package is much fancier.
In subsequent alpha releases of Python 2.5, I'll add a brief
introduction that shows some basic usage of the module.
To load a shared library or DLL, you must create an instance of the
\class{CDLL} class and provide the name or path of the shared library
or DLL. Once that's done, you can call arbitrary functions
by accessing them as attributes of the \class{CDLL} object.
\begin{verbatim}
import ctypes
libc = ctypes.CDLL('libc.so.6')
result = libc.printf("Line of output\n")
\end{verbatim}
Type constructors for the various C types are provided: \function{c_int},
\function{c_float}, \function{c_double}, \function{c_char_p} (equivalent to \ctype{char *}), and so forth. Unlike Python's types, the C versions are all mutable; you can assign to their \member{value} attribute
to change the wrapped value. Python integers and strings will be automatically
converted to the corresponding C types, but for other types you
must call the correct type constructor. (And I mean \emph{must};
getting it wrong will often result in the interpreter crashing
with a segmentation fault.)
You shouldn't use \function{c_char_p} with a Python string when the C function will be modifying the memory area, because Python strings are
supposed to be immutable; breaking this rule will cause puzzling bugs. When you need a modifiable memory area,
use \function{create_string_buffer():
\begin{verbatim}
s = "this is a string"
buf = ctypes.create_string_buffer(s)
libc.strfry(buf)
\end{verbatim}
C functions are assumed to return integers, but you can set
the \member{restype} attribute of the function object to
change this:
\begin{verbatim}
>>> libc.atof('2.71828')
-1783957616
>>> libc.atof.restype = ctypes.c_double
>>> libc.atof('2.71828')
2.71828
\end{verbatim}
\module{ctypes} also provides a wrapper for Python's C API
as the \code{ctypes.pythonapi} object. This object does \emph{not}
release the global interpreter lock before calling a function, because the lock must be held when calling into the interpreter's code.
There's a \class{py_object()} type constructor that will create a
