EVOLUTION-MANAGER

Edit File: cdef.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
 <title>Preparing and Distributing modules &mdash; CFFI 1.6.0 documentation</title>
 
 <link rel="stylesheet" href="_static/default.css" type="text/css" />
 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 
 <script type="text/javascript">
 var DOCUMENTATION_OPTIONS = {
 URL_ROOT: '',
 VERSION: '1.6.0',
 COLLAPSE_INDEX: false,
 FILE_SUFFIX: '.html',
 HAS_SOURCE: true
 };
 </script>
 <script type="text/javascript" src="_static/jquery.js"></script>
 <script type="text/javascript" src="_static/underscore.js"></script>
 <script type="text/javascript" src="_static/doctools.js"></script>
 <link rel="top" title="CFFI 1.6.0 documentation" href="index.html" />
 <link rel="next" title="Using CFFI for embedding" href="embedding.html" />
 <link rel="prev" title="CFFI Reference" href="ref.html" /> 
 </head>
 <body>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="embedding.html" title="Using CFFI for embedding"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="ref.html" title="CFFI Reference"
 accesskey="P">previous</a> |</li>
 <li><a href="index.html">CFFI 1.6.0 documentation</a> &raquo;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body">
 
 <div class="section" id="preparing-and-distributing-modules">
<h1><a class="toc-backref" href="#id6">Preparing and Distributing modules</a><a class="headerlink" href="#preparing-and-distributing-modules" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
Contents
<ul class="simple">
<li><a class="reference internal" href="#preparing-and-distributing-modules" id="id6">Preparing and Distributing modules</a><ul>
<li><a class="reference internal" href="#ffi-cdef-declaring-types-and-functions" id="id7">ffi.cdef(): declaring types and functions</a></li>
<li><a class="reference internal" href="#ffi-dlopen-loading-libraries-in-abi-mode" id="id8">ffi.dlopen(): loading libraries in ABI mode</a></li>
<li><a class="reference internal" href="#ffi-set-source-preparing-out-of-line-modules" id="id9">ffi.set_source(): preparing out-of-line modules</a></li>
<li><a class="reference internal" href="#letting-the-c-compiler-fill-the-gaps" id="id10">Letting the C compiler fill the gaps</a></li>
<li><a class="reference internal" href="#ffi-compile-etc-compiling-out-of-line-modules" id="id11">ffi.compile() etc.: compiling out-of-line modules</a></li>
<li><a class="reference internal" href="#ffi-include-combining-multiple-cffi-interfaces" id="id12">ffi.include(): combining multiple CFFI interfaces</a></li>
<li><a class="reference internal" href="#ffi-cdef-limitations" id="id13">ffi.cdef() limitations</a></li>
<li><a class="reference internal" href="#debugging-dlopen-ed-c-libraries" id="id14">Debugging dlopen&#8217;ed C libraries</a></li>
<li><a class="reference internal" href="#ffi-verify-in-line-api-mode" id="id15">ffi.verify(): in-line API-mode</a></li>
<li><a class="reference internal" href="#upgrading-from-cffi-0-9-to-cffi-1-0" id="id16">Upgrading from CFFI 0.9 to CFFI 1.0</a></li>
</ul>
</li>
</ul>
</div>
There are three or four different ways to use CFFI in a project.
In order of complexity:
<ul>
<li>The &#8220;in-line&#8221;, &#8220;ABI mode&#8221;:
<div class="highlight-python"><div class="highlight"><pre>import cffi

# use ffi and lib here
</pre></div>
</div>
</li>
</ul>
<ul id="out-of-line-abi">
<li>The &#8220;out-of-line&#8221;, but still &#8220;ABI mode&#8221;, useful to organize
the code and reduce the import time:
<div class="highlight-python"><div class="highlight"><pre># in a separate file &quot;package/foo_build.py&quot;
import cffi

# use ffi and lib here
</pre></div>
</div>
</li>
</ul>
<ul id="out-of-line-api">
<li>The &#8220;out-of-line&#8221;, &#8220;API mode&#8221; gives you the most flexibility to
access a C library at the level of C, instead of at the binary
level:
<div class="highlight-python"><div class="highlight"><pre># in a separate file &quot;package/foo_build.py&quot;
import cffi

# use ffi and lib here
</pre></div>
</div>
</li>
</ul>
<ul id="distutils-setuptools">
<li>Finally, you can (but don&#8217;t have to) use CFFI&#8217;s Distutils or
Setuptools integration when writing a <tt class="docutils literal">setup.py</tt>. For
Distutils (only in out-of-line API mode):
<div class="highlight-python"><div class="highlight"><pre># setup.py (requires CFFI to be installed first)
from distutils.core import setup

import foo_build # possibly with sys.path tricks to find it

setup(
 ...,
 ext_modules=[foo_build.ffi.distutils_extension()],
)
</pre></div>
</div>
For Setuptools (out-of-line, but works in ABI or API mode;
recommended):
<div class="highlight-python"><div class="highlight"><pre># setup.py (with automatic dependency tracking)
from setuptools import setup

setup(
 ...,
 setup_requires=[&quot;cffi&gt;=1.0.0&quot;],
 cffi_modules=[&quot;package/foo_build.py:ffi&quot;],
 install_requires=[&quot;cffi&gt;=1.0.0&quot;],
)
</pre></div>
</div>
</li>
<li>Note that some bundler tools that try to find all modules used by a
project, like PyInstaller, will miss <tt class="docutils literal">_cffi_backend</tt> in the
out-of-line mode because your program contains no explicit <tt class="docutils literal">import
cffi</tt> or <tt class="docutils literal">import _cffi_backend</tt>. You need to add
<tt class="docutils literal">_cffi_backend</tt> explicitly (as a &#8220;hidden import&#8221; in PyInstaller,
but it can also be done more generally by adding the line <tt class="docutils literal">import
_cffi_backend</tt> in your main program).
</li>
</ul>
Note that CFFI actually contains two different <tt class="docutils literal">FFI</tt> classes. The
page <a class="reference external" href="using.html">Using the ffi/lib objects</a> describes the common functionality.
It is what you get in the <tt class="docutils literal">from package._foo import ffi</tt> lines above.
On the other hand, the extended <tt class="docutils literal">FFI</tt> class is the one you get from
<tt class="docutils literal">import cffi; ffi = cffi.FFI()</tt>. It has the same functionality (for
in-line use), but also the extra methods described below (to prepare
the FFI).
The reason for this split of functionality is that a regular program
using CFFI out-of-line does not need to import the <tt class="docutils literal">cffi</tt> pure
Python package at all. (Internally it still needs <tt class="docutils literal">_cffi_backend</tt>,
a C extension module that comes with CFFI; this is why CFFI is also
listed in <tt class="docutils literal">install_requires=..</tt> above. In the future this might be
split into a different PyPI package that only installs
<tt class="docutils literal">_cffi_backend</tt>.)
Note that a few small differences do exist: notably, <tt class="docutils literal">from _foo import
ffi</tt> returns an object of a type written in C, which does not let you
add random attributes to it (nor does it have all the
underscore-prefixed internal attributes of the Python version).
Similarly, the <tt class="docutils literal">lib</tt> objects returned by the C version are read-only,
apart from writes to global variables. Also, <tt class="docutils literal">lib.__dict__</tt> does
not work before version 1.2 or if <tt class="docutils literal">lib</tt> happens to declare a name
called <tt class="docutils literal">__dict__</tt> (use instead <tt class="docutils literal">dir(lib)</tt>). The same is true
for <tt class="docutils literal">lib.__class__</tt> before version 1.4.
<div class="section" id="ffi-cdef-declaring-types-and-functions">
<h2><a class="toc-backref" href="#id7">ffi.cdef(): declaring types and functions</a><a class="headerlink" href="#ffi-cdef-declaring-types-and-functions" title="Permalink to this headline">¶</a></h2>
ffi.cdef(source): parses the given C source.
It registers all the functions, types, constants and global variables in
the C source. The types can be used immediately in <tt class="docutils literal">ffi.new()</tt> and
other functions. Before you can access the functions and global
variables, you need to give <tt class="docutils literal">ffi</tt> another piece of information: where
they actually come from (which you do with either <tt class="docutils literal">ffi.dlopen()</tt> or
<tt class="docutils literal">ffi.set_source()</tt>).
The C source is parsed internally (using <tt class="docutils literal">pycparser</tt>). This code
cannot contain <tt class="docutils literal">#include</tt>. It should typically be a self-contained
piece of declarations extracted from a man page. The only things it
can assume to exist are the standard types:
<ul class="simple">
<li>char, short, int, long, long long (both signed and unsigned)</li>
<li>float, double, long double</li>
<li>intN_t, uintN_t (for N=8,16,32,64), intptr_t, uintptr_t, ptrdiff_t,
size_t, ssize_t</li>
<li>wchar_t (if supported by the backend)</li>
<li>_Bool and bool (equivalent). If not directly supported by the C
compiler, this is declared with the size of <tt class="docutils literal">unsigned char</tt>.</li>
<li>FILE. You can declare C functions taking a <tt class="docutils literal">FILE *</tt> argument and
call them with a Python file object. If needed, you can also do
<tt class="docutils literal">c_f = ffi.cast(&quot;FILE *&quot;, fileobj)</tt> and then pass around <tt class="docutils literal">c_f</tt>.</li>
<li>all <a class="reference external" href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751%28v=vs.85%29.aspx">common Windows types</a> are defined if you run
on Windows (<tt class="docutils literal">DWORD</tt>, <tt class="docutils literal">LPARAM</tt>, etc.). Changed in version 0.9: the
types <tt class="docutils literal">TBYTE TCHAR LPCTSTR PCTSTR LPTSTR PTSTR PTBYTE PTCHAR</tt> are no
longer automatically defined; see <a class="reference internal" href="#ffi-set-unicode">ffi.set_unicode()</a>.</li>
<li>New in version 0.9.3: the other standard integer types from
stdint.h, like <tt class="docutils literal">intmax_t</tt>, as long as they map to integers of 1,
2, 4 or 8 bytes. Larger integers are not supported.</li>
</ul>
The declarations can also contain &#8220;<tt class="docutils literal">...</tt>&#8221; at various places; these are
placeholders that will be completed by the compiler. More information
about it below in <a class="reference internal" href="#letting-the-c-compiler-fill-the-gaps">Letting the C compiler fill the gaps</a>.
Note that all standard type names listed above are handled as
defaults only (apart from the ones that are keywords in the C
language). If your <tt class="docutils literal">cdef</tt> contains an explicit typedef that
redefines one of the types above, then the default described above is
ignored. (This is a bit hard to implement cleanly, so in some corner
cases it might fail, notably with the error <tt class="docutils literal">Multiple type specifiers
with a type tag</tt>. Please report it as a bug if it does.)
Multiple calls to <tt class="docutils literal">ffi.cdef()</tt> are possible. Beware that it can be
slow to call <tt class="docutils literal">ffi.cdef()</tt> a lot of times, a consideration that is
important mainly in in-line mode.
The <tt class="docutils literal">ffi.cdef()</tt> call takes an optional
argument <tt class="docutils literal">packed</tt>: if True, then all structs declared within
this cdef are &#8220;packed&#8221;. (If you need both packed and non-packed
structs, use several cdefs in sequence.) This
has a meaning similar to <tt class="docutils literal">__attribute__((packed))</tt> in GCC. It
specifies that all structure fields should have an alignment of one
byte. (Note that the packed attribute has no effect on bit fields so
far, which mean that they may be packed differently than on GCC.
Also, this has no effect on structs declared with <tt class="docutils literal">&quot;...;&quot;</tt>&#8212;more
about it later in <a class="reference internal" href="#letting-the-c-compiler-fill-the-gaps">Letting the C compiler fill the gaps</a>.)
Note that you can use the type-qualifiers <tt class="docutils literal">const</tt> and <tt class="docutils literal">restrict</tt>
(but not <tt class="docutils literal">__restrict</tt> or <tt class="docutils literal">__restrict__</tt>) in the <tt class="docutils literal">cdef()</tt>, but
this has no effect on the cdata objects that you get at run-time (they
are never <tt class="docutils literal">const</tt>). The effect is limited to knowing if a global
variable is meant to be a constant or not. Also, new in version
1.3: when using <tt class="docutils literal">set_source()</tt> or <tt class="docutils literal">verify()</tt>, these two
qualifiers are copied from the cdef to the generated C code; this
fixes warnings by the C compiler.
Note a trick if you copy-paste code from sources in which there are
extra macros (for example, the Windows documentation uses SAL
annotations like <tt class="docutils literal">_In_</tt> or <tt class="docutils literal">_Out_</tt>). These hints must be removed
in the string given to cdef(), but it can be done programmatically
like this:
<div class="highlight-python"><div class="highlight"><pre>ffi.cdef(re.sub(r&quot;\b(_In_|_Inout_|_Out_|_Outptr_)(opt_)?\b&quot;, &quot; &quot;,
 &quot;&quot;&quot;
 DWORD WINAPI GetModuleFileName(
 _In_opt_ HMODULE hModule,
 _Out_ LPTSTR lpFilename,
 _In_ DWORD nSize
 );
 &quot;&quot;&quot;))
</pre></div>
</div>
ffi.set_unicode(enabled_flag): Windows: if <tt class="docutils literal">enabled_flag</tt> is
True, enable the <tt class="docutils literal">UNICODE</tt> and <tt class="docutils literal">_UNICODE</tt> defines in C, and
declare the types <tt class="docutils literal">TBYTE TCHAR LPCTSTR PCTSTR LPTSTR PTSTR PTBYTE
PTCHAR</tt> to be (pointers to) <tt class="docutils literal">wchar_t</tt>. If <tt class="docutils literal">enabled_flag</tt> is
False, declare these types to be (pointers to) plain 8-bit characters.
(These types are not predeclared at all if you don&#8217;t call
<tt class="docutils literal">set_unicode()</tt>.) New in version 0.9.
The reason behind this method is that a lot of standard functions have
two versions, like <tt class="docutils literal">MessageBoxA()</tt> and <tt class="docutils literal">MessageBoxW()</tt>. The
official interface is <tt class="docutils literal">MessageBox()</tt> with arguments like
<tt class="docutils literal">LPTCSTR</tt>. Depending on whether <tt class="docutils literal">UNICODE</tt> is defined or not, the
standard header renames the generic function name to one of the two
specialized versions, and declares the correct (unicode or not) types.
Usually, the right thing to do is to call this method with True. Be
aware (particularly on Python 2) that, afterwards, you need to pass unicode
strings as arguments instead of byte strings. (Before cffi version 0.9,
<tt class="docutils literal">TCHAR</tt> and friends where hard-coded as unicode, but <tt class="docutils literal">UNICODE</tt> was,
inconsistently, not defined by default.)
</div>
<div class="section" id="ffi-dlopen-loading-libraries-in-abi-mode">
<h2><a class="toc-backref" href="#id8">ffi.dlopen(): loading libraries in ABI mode</a><a class="headerlink" href="#ffi-dlopen-loading-libraries-in-abi-mode" title="Permalink to this headline">¶</a></h2>
<tt class="docutils literal">ffi.dlopen(libpath, [flags])</tt>: this function opens a shared library and
returns a module-like library object. Use this when you are fine with
the limitations of ABI-level access to the system. In case of doubt, read
again <a class="reference external" href="overview.html#abi-versus-api">ABI versus API</a> in the overview.
You can use the library object to call the functions previously
declared by <tt class="docutils literal">ffi.cdef()</tt>, to read constants, and to read or write
global variables. Note that you can use a single <tt class="docutils literal">cdef()</tt> to
declare functions from multiple libraries, as long as you load each of
them with <tt class="docutils literal">dlopen()</tt> and access the functions from the correct one.
The <tt class="docutils literal">libpath</tt> is the file name of the shared library, which can
contain a full path or not (in which case it is searched in standard
locations, as described in <tt class="docutils literal">man dlopen</tt>), with extensions or not.
Alternatively, if <tt class="docutils literal">libpath</tt> is None, it returns the standard C library
(which can be used to access the functions of glibc, on Linux).
Let me state it again: this gives ABI-level access to the library, so
you need to have all types declared manually exactly as they were
while the library was made. No checking is done. Mismatches can
cause random crashes.
Note that only functions and global variables live in library objects;
the types exist in the <tt class="docutils literal">ffi</tt> instance independently of library objects.
This is due to the C model: the types you declare in C are not tied to a
particular library, as long as you <tt class="docutils literal">#include</tt> their headers; but you
cannot call functions from a library without linking it in your program,
as <tt class="docutils literal">dlopen()</tt> does dynamically in C.
For the optional <tt class="docutils literal">flags</tt> argument, see <tt class="docutils literal">man dlopen</tt> (ignored on
Windows). It defaults to <tt class="docutils literal">ffi.RTLD_NOW</tt>.
This function returns a &#8220;library&#8221; object that gets closed when it goes
out of scope. Make sure you keep the library object around as long as
needed. (Alternatively, the out-of-line FFIs have a method
<tt class="docutils literal">ffi.dlclose(lib)</tt>.)
Note: the old version of <tt class="docutils literal">ffi.dlopen()</tt> from the in-line ABI mode
tries to use <tt class="docutils literal">ctypes.util.find_library()</tt> if it cannot directly find
the library. The newer out-of-line <tt class="docutils literal">ffi.dlopen()</tt> no longer does it
automatically; it simply passes the argument it receives to the
underlying <tt class="docutils literal">dlopen()</tt> or <tt class="docutils literal">LoadLibrary()</tt> function. If needed, it
is up to you to use <tt class="docutils literal">ctypes.util.find_library()</tt> or any other way to
look for the library&#8217;s filename. This also means that
<tt class="docutils literal">ffi.dlopen(None)</tt> no longer work on Windows; try instead
<tt class="docutils literal">ffi.dlopen(ctypes.util.find_library('c'))</tt>.
</div>
<div class="section" id="ffi-set-source-preparing-out-of-line-modules">
<h2><a class="toc-backref" href="#id9">ffi.set_source(): preparing out-of-line modules</a><a class="headerlink" href="#ffi-set-source-preparing-out-of-line-modules" title="Permalink to this headline">¶</a></h2>
ffi.set_source(module_name, c_header_source, [**keywords...]):
prepare the ffi for producing out-of-line an external module called
<tt class="docutils literal">module_name</tt>. New in version 1.0.
<tt class="docutils literal">ffi.set_source()</tt> by itself does not write any file, but merely
records its arguments for later. It can therefore be called before or
after <tt class="docutils literal">ffi.cdef()</tt>.
In ABI mode, you call <tt class="docutils literal">ffi.set_source(module_name, None)</tt>. The
argument is the name (or dotted name inside a package) of the Python
module to generate. In this mode, no C compiler is called.
In API mode, the <tt class="docutils literal">c_header_source</tt> argument is a string that
will be pasted into the .c file generated. This piece of C code
typically contains some <tt class="docutils literal">#include</tt>, but may also contain more,
like definitions for custom &#8220;wrapper&#8221; C functions. The goal is that
the .c file can be generated like this:
<div class="highlight-python"><pre>// C file "module_name.c"
#include &lt;Python.h&gt;

...c_header_source...

...magic code...</pre>
</div>
where the &#8220;magic code&#8221; is automatically generated from the <tt class="docutils literal">cdef()</tt>.
For example, if the <tt class="docutils literal">cdef()</tt> contains <tt class="docutils literal">int foo(int x);</tt> then the
magic code will contain logic to call the function <tt class="docutils literal">foo()</tt> with an
integer argument, itself wrapped inside some CPython or PyPy-specific
code.
The keywords arguments to <tt class="docutils literal">set_source()</tt> control how the C compiler
will be called. They are passed directly to <a class="reference external" href="http://docs.python.org/distutils/setupscript.html#describing-extension-modules">distutils</a> or <a class="reference external" href="https://pythonhosted.org/setuptools/setuptools.html">setuptools</a>
and include at least <tt class="docutils literal">sources</tt>, <tt class="docutils literal">include_dirs</tt>, <tt class="docutils literal">define_macros</tt>,
<tt class="docutils literal">undef_macros</tt>, <tt class="docutils literal">libraries</tt>, <tt class="docutils literal">library_dirs</tt>, <tt class="docutils literal">extra_objects</tt>,
<tt class="docutils literal">extra_compile_args</tt> and <tt class="docutils literal">extra_link_args</tt>. You typically need at
least <tt class="docutils literal">libraries=['foo']</tt> in order to link with <tt class="docutils literal">libfoo.so</tt> or
<tt class="docutils literal">libfoo.so.X.Y</tt>, or <tt class="docutils literal">foo.dll</tt> on Windows. The <tt class="docutils literal">sources</tt> is a
list of extra .c files compiled and linked together (the file
<tt class="docutils literal">module_name.c</tt> shown above is always generated and automatically added as the
first argument to <tt class="docutils literal">sources</tt>). See the distutils documentations for
<a class="reference external" href="http://docs.python.org/distutils/setupscript.html#library-options">more information about the other arguments</a>.
An extra keyword argument processed internally is
<tt class="docutils literal">source_extension</tt>, defaulting to <tt class="docutils literal">&quot;.c&quot;</tt>. The file generated will
be actually called <tt class="docutils literal">module_name + source_extension</tt>. Example for
C++ (but note that there are still a few known issues of C-versus-C++
compatibility):
<div class="highlight-python"><div class="highlight"><pre>ffi.set_source(&quot;mymodule&quot;, &#39;&#39;&#39;
extern &quot;C&quot; {
 int somefunc(int somearg) { return real_cpp_func(somearg); }
}
&#39;&#39;&#39;, source_extension=&#39;.cpp&#39;)
</pre></div>
</div>
</div>
<div class="section" id="letting-the-c-compiler-fill-the-gaps">
<h2><a class="toc-backref" href="#id10">Letting the C compiler fill the gaps</a><a class="headerlink" href="#letting-the-c-compiler-fill-the-gaps" title="Permalink to this headline">¶</a></h2>
If you are using a C compiler (&#8220;API mode&#8221;), then:
<ul class="simple">
<li>functions taking or returning integer or float-point arguments can be
misdeclared: if e.g. a function is declared by <tt class="docutils literal">cdef()</tt> as taking a
<tt class="docutils literal">int</tt>, but actually takes a <tt class="docutils literal">long</tt>, then the C compiler handles the
difference.</li>
<li>other arguments are checked: you get a compilation warning or error
if you pass a <tt class="docutils literal">int *</tt> argument to a function expecting a <tt class="docutils literal">long *</tt>.</li>
<li>similarly, most other things declared in the <tt class="docutils literal">cdef()</tt> are checked,
to the best we implemented so far; mistakes give compilation
warnings or errors.</li>
</ul>
Moreover, you can use &#8220;<tt class="docutils literal">...</tt>&#8221; (literally, dot-dot-dot) in the
<tt class="docutils literal">cdef()</tt> at various places, in order to ask the C compiler to fill
in the details. These places are:
<ul>
<li>structure declarations: any <tt class="docutils literal">struct { }</tt> that ends with &#8220;<tt class="docutils literal">...;</tt>&#8221; as
the last &#8220;field&#8221; is
partial: it may be missing fields and/or have them declared out of order.
This declaration will be corrected by the compiler. (But note that you
can only access fields that you declared, not others.) Any <tt class="docutils literal">struct</tt>
declaration which doesn&#8217;t use &#8220;<tt class="docutils literal">...</tt>&#8221; is assumed to be exact, but this is
checked: you get an error if it is not correct.
</li>
<li>New in version 1.1: integer types: the syntax &#8220;<tt class="docutils literal">typedef
int... foo_t;</tt>&#8221; declares the type <tt class="docutils literal">foo_t</tt> as an integer type
whose exact size and signedness is not specified. The compiler will
figure it out. (Note that this requires <tt class="docutils literal">set_source()</tt>; it does
not work with <tt class="docutils literal">verify()</tt>.) The <tt class="docutils literal">int...</tt> can be replaced with
<tt class="docutils literal">long...</tt> or <tt class="docutils literal">unsigned long long...</tt> or any other primitive
integer type, with no effect. The type will always map to one of
<tt class="docutils literal">(u)int(8,16,32,64)_t</tt> in Python, but in the generated C code,
only <tt class="docutils literal">foo_t</tt> is used.
</li>
<li>New in version 1.3: floating-point types: &#8220;<tt class="docutils literal">typedef
float... foo_t;</tt>&#8221; (or equivalently &#8220;<tt class="docutils literal">typedef double... foo_t;</tt>&#8221;)
declares <tt class="docutils literal">foo_t</tt> as a-float-or-a-double; the compiler will figure
out which it is. Note that if the actual C type is even larger
(<tt class="docutils literal">long double</tt> on some platforms), then compilation will fail.
The problem is that the Python &#8220;float&#8221; type cannot be used to store
the extra precision. (Use the non-dot-dot-dot syntax <tt class="docutils literal">typedef long
double foo_t;</tt> as usual, which returns values that are not Python
floats at all but cdata &#8220;long double&#8221; objects.)
</li>
<li>unknown types: the syntax &#8220;<tt class="docutils literal">typedef ... foo_t;</tt>&#8221; declares the type
<tt class="docutils literal">foo_t</tt> as opaque. Useful mainly for when the API takes and returns
<tt class="docutils literal">foo_t *</tt> without you needing to look inside the <tt class="docutils literal">foo_t</tt>. Also
works with &#8220;<tt class="docutils literal">typedef ... *foo_p;</tt>&#8221; which declares the pointer type
<tt class="docutils literal">foo_p</tt> without giving a name to the opaque type itself. Note that
such an opaque struct has no known size, which prevents some operations
from working (mostly like in C). You cannot use this syntax to
declare a specific type, like an integer type! It declares opaque
struct-like types only. In some cases you need to say that
<tt class="docutils literal">foo_t</tt> is not opaque, but just a struct where you don&#8217;t know any
field; then you would use &#8220;<tt class="docutils literal">typedef struct { ...; } foo_t;</tt>&#8221;.
</li>
<li>array lengths: when used as structure fields or in global variables,
arrays can have an unspecified length, as in &#8220;<tt class="docutils literal">int n[...];</tt>&#8221;. The
length is completed by the C compiler.
This is slightly different from &#8220;<tt class="docutils literal">int n[];</tt>&#8221;, because the latter
means that the length is not known even to the C compiler, and thus
no attempt is made to complete it. New in version 1.1: support
for multidimensional arrays: &#8220;<tt class="docutils literal">int n[...][...];</tt>&#8221;.
New in version 1.2: &#8220;<tt class="docutils literal">int m[][...];</tt>&#8221;, i.e. <tt class="docutils literal">...</tt> can be used
in the innermost dimensions without being also used in the outermost
dimension. In the example given, the length of the <tt class="docutils literal">m</tt> array is
assumed not to be known to the C compiler, but the length of every
item (like the sub-array <tt class="docutils literal">m[0]</tt>) is always known the C compiler.
In other words, only the outermost dimension can be specified as
<tt class="docutils literal">[]</tt>, both in C and in CFFI, but any dimension can be given as
<tt class="docutils literal">[...]</tt> in CFFI.
</li>
<li>enums: if you don&#8217;t know the exact order (or values) of the declared
constants, then use this syntax: &#8220;<tt class="docutils literal">enum foo { A, B, C, ... };</tt>&#8221;
(with a trailing &#8220;<tt class="docutils literal">...</tt>&#8221;). The C compiler will be used to figure
out the exact values of the constants. An alternative syntax is
&#8220;<tt class="docutils literal">enum foo { A=..., B, C };</tt>&#8221; or even
&#8220;<tt class="docutils literal">enum foo { A=..., B=..., C=... };</tt>&#8221;. Like
with structs, an <tt class="docutils literal">enum</tt> without &#8220;<tt class="docutils literal">...</tt>&#8221; is assumed to
be exact, and this is checked.
</li>
<li>integer constants and macros: you can write in the <tt class="docutils literal">cdef</tt> the line
&#8220;<tt class="docutils literal">#define FOO ...</tt>&#8221;, with any macro name FOO but with <tt class="docutils literal">...</tt> as
a value. Provided the macro
is defined to be an integer value, this value will be available via
an attribute of the library object. The
same effect can be achieved by writing a declaration
<tt class="docutils literal">static const int FOO;</tt>. The latter is more general because it
supports other types than integer types (note: the C syntax is then
to write the <tt class="docutils literal">const</tt> together with the variable name, as in
<tt class="docutils literal">static char *const FOO;</tt>).
</li>
</ul>
Currently, it is not supported to find automatically which of the
various integer or float types you need at which place.
If a type is named, and an integer type, then use <tt class="docutils literal">typedef
int... the_type_name;</tt>. In the case of
function arguments or return type, when it is a simple integer/float
type, it may be misdeclared (if you misdeclare a function <tt class="docutils literal">void
f(long)</tt> as <tt class="docutils literal">void f(int)</tt>, it still works, but you have to call it
with arguments that fit an int). But it doesn&#8217;t work any longer for
more complex types (e.g. you cannot misdeclare a <tt class="docutils literal">int *</tt> argument as
<tt class="docutils literal">long *</tt>) or in other locations (e.g. a global array <tt class="docutils literal">int a[5];</tt>
must not be misdeclared <tt class="docutils literal">long a[5];</tt>). CFFI considers <a class="reference internal" href="#all-types-listed-above">all types listed
above</a> as primitive (so <tt class="docutils literal">long long a[5];</tt> and <tt class="docutils literal">int64_t a[5]</tt> are
different declarations).
</div>
<div class="section" id="ffi-compile-etc-compiling-out-of-line-modules">
<h2><a class="toc-backref" href="#id11">ffi.compile() etc.: compiling out-of-line modules</a><a class="headerlink" href="#ffi-compile-etc-compiling-out-of-line-modules" title="Permalink to this headline">¶</a></h2>
You can use one of the following functions to actually generate the
.py or .c file prepared with <tt class="docutils literal">ffi.set_source()</tt> and <tt class="docutils literal">ffi.cdef()</tt>.
Note that these function won&#8217;t overwrite a .py/.c file with exactly
the same content, to preserve the mtime. In some cases where you need
the mtime to be updated anyway, delete the file before calling the
functions.
ffi.compile(tmpdir=&#8217;.&#8217;, verbose=False):
explicitly generate the .py or .c file,
and (if .c) compile it. The output file is (or are) put in the
directory given by <tt class="docutils literal">tmpdir</tt>. In the examples given here, we use
<tt class="docutils literal">if __name__ == &quot;__main__&quot;: ffi.compile()</tt> in the build scripts&#8212;if
they are directly executed, this makes them rebuild the .py/.c file in
the current directory. (Note: if a package is specified in the call
to <tt class="docutils literal">set_source()</tt>, then a corresponding subdirectory of the <tt class="docutils literal">tmpdir</tt>
is used.)
New in version 1.4: <tt class="docutils literal">verbose</tt> argument. If True, it prints the
usual distutils output, including the command lines that call the
compiler. (This parameter might be changed to True by default in a
future release.)
ffi.emit_python_code(filename): generate the given .py file (same
as <tt class="docutils literal">ffi.compile()</tt> for ABI mode, with an explicitly-named file to
write). If you choose, you can include this .py file pre-packaged in
your own distributions: it is identical for any Python version (2 or
3).
ffi.emit_c_code(filename): generate the given .c file (for API
mode) without compiling it. Can be used if you have some other method
to compile it, e.g. if you want to integrate with some larger build
system that will compile this file for you. You can also distribute
the .c file: unless the build script you used depends on the OS or
platform, the .c file itself is generic (it would be exactly the same
if produced on a different OS, with a different version of CPython, or
with PyPy; it is done with generating the appropriate <tt class="docutils literal">#ifdef</tt>).
ffi.distutils_extension(tmpdir=&#8217;build&#8217;, verbose=True): for
distutils-based <tt class="docutils literal">setup.py</tt> files. Calling this creates the .c file
if needed in the given <tt class="docutils literal">tmpdir</tt>, and returns a
<tt class="docutils literal">distutils.core.Extension</tt> instance.
For Setuptools, you use instead the line
<tt class="docutils literal">cffi_modules=[&quot;path/to/foo_build.py:ffi&quot;]</tt> in <tt class="docutils literal">setup.py</tt>. This
line asks Setuptools to import and use a helper provided by CFFI,
which in turn executes the file <tt class="docutils literal">path/to/foo_build.py</tt> (as with
<tt class="docutils literal">execfile()</tt>) and looks up its global variable called <tt class="docutils literal">ffi</tt>. You
can also say <tt class="docutils literal">cffi_modules=[&quot;path/to/foo_build.py:maker&quot;]</tt>, where
<tt class="docutils literal">maker</tt> names a global function; it is called with no argument and
is supposed to return a <tt class="docutils literal">FFI</tt> object.
</div>
<div class="section" id="ffi-include-combining-multiple-cffi-interfaces">
<h2><a class="toc-backref" href="#id12">ffi.include(): combining multiple CFFI interfaces</a><a class="headerlink" href="#ffi-include-combining-multiple-cffi-interfaces" title="Permalink to this headline">¶</a></h2>
ffi.include(other_ffi): includes the typedefs, structs, unions,
enums and constants defined in another FFI instance. This is meant
for large projects where one CFFI-based interface depends on some
types declared in a different CFFI-based interface.
Note that you should only use one ffi object per library; the intended
usage of ffi.include() is if you want to interface with several
inter-dependent libraries. For only one library, make one <tt class="docutils literal">ffi</tt>
object. (You can write several <tt class="docutils literal">cdef()</tt> calls over the same <tt class="docutils literal">ffi</tt>
from several Python files, if one file would be too large.)
For out-of-line modules, the <tt class="docutils literal">ffi.include(other_ffi)</tt> line should
occur in the build script, and the <tt class="docutils literal">other_ffi</tt> argument should be
another FFI that comes from another build script. When the two build
scripts are turned into generated files, say <tt class="docutils literal">_ffi.so</tt> and
<tt class="docutils literal">_other_ffi.so</tt>, then importing <tt class="docutils literal">_ffi.so</tt> will internally cause
<tt class="docutils literal">_other_ffi.so</tt> to be imported. At that point, the real
declarations from <tt class="docutils literal">_other_ffi.so</tt> are combined with the real
declarations from <tt class="docutils literal">_ffi.so</tt>.
The usage of <tt class="docutils literal">ffi.include()</tt> is the cdef-level equivalent of a
<tt class="docutils literal">#include</tt> in C, where a part of the program might include types and
functions defined in another part for its own usage. You can see on
the <tt class="docutils literal">ffi</tt> object (and associated <tt class="docutils literal">lib</tt> objects on the including
side) the types and constants declared on the included side. In API
mode, you can also see the functions and global variables directly.
In ABI mode, these must be accessed via the original <tt class="docutils literal">other_lib</tt>
object returned by the <tt class="docutils literal">dlopen()</tt> method on <tt class="docutils literal">other_ffi</tt>.
</div>
<div class="section" id="ffi-cdef-limitations">
<h2><a class="toc-backref" href="#id13">ffi.cdef() limitations</a><a class="headerlink" href="#ffi-cdef-limitations" title="Permalink to this headline">¶</a></h2>
All of the ANSI C declarations should be supported in <tt class="docutils literal">cdef()</tt>,
and some of C99. (This excludes any <tt class="docutils literal">#include</tt> or <tt class="docutils literal">#ifdef</tt>.)
Known missing features that are GCC or MSVC extensions:
<ul class="simple">
<li>Any <tt class="docutils literal">__attribute__</tt> or <tt class="docutils literal">#pragma pack(n)</tt></li>
<li>Additional types: complex numbers, special-size floating and fixed
point types, vector types, and so on. You might be able to access an
array of complex numbers by declaring it as an array of <tt class="docutils literal">struct
my_complex { double real, imag; }</tt>, but in general you should declare
them as <tt class="docutils literal">struct { ...; }</tt> and cannot access them directly. This
means that you cannot call any function which has an argument or
return value of this type (this would need added support in libffi).
You need to write wrapper functions in C, e.g. <tt class="docutils literal">void
foo_wrapper(struct my_complex c) { foo(c.real + c.imag*1j); }</tt>, and
call <tt class="docutils literal">foo_wrapper</tt> rather than <tt class="docutils literal">foo</tt> directly.</li>
<li>Function pointers with non-default calling conventions (e.g. on
Windows, &#8220;stdcall&#8221;).</li>
</ul>
Note that declarations like <tt class="docutils literal">int field[];</tt> in
structures are interpreted as variable-length structures. Declarations
like <tt class="docutils literal">int field[...];</tt> on the other hand are arrays whose length is
going to be completed by the compiler. You can use <tt class="docutils literal">int field[];</tt>
for array fields that are not, in fact, variable-length; it works too,
but in this case, as CFFI
believes it cannot ask the C compiler for the length of the array, you
get reduced safety checks: for example, you risk overwriting the
following fields by passing too many array items in the constructor.
New in version 1.2:
Thread-local variables (<tt class="docutils literal">__thread</tt>) can be accessed, as well as
variables defined as dynamic macros (<tt class="docutils literal">#define myvar&nbsp; (*fetchme())</tt>).
Before version 1.2, you need to write getter/setter functions.
</div>
<div class="section" id="debugging-dlopen-ed-c-libraries">
<h2><a class="toc-backref" href="#id14">Debugging dlopen&#8217;ed C libraries</a><a class="headerlink" href="#debugging-dlopen-ed-c-libraries" title="Permalink to this headline">¶</a></h2>
A few C libraries are actually hard to use correctly in a <tt class="docutils literal">dlopen()</tt>
setting. This is because most C libraries are intented for, and tested
with, a situation where they are linked with another program, using
either static linking or dynamic linking &#8212; but from a program written
in C, at start-up, using the linker&#8217;s capabilities instead of
<tt class="docutils literal">dlopen()</tt>.
This can occasionally create issues. You would have the same issues in
another setting than CFFI, like with <tt class="docutils literal">ctypes</tt> or even plain C code that
calls <tt class="docutils literal">dlopen()</tt>. This section contains a few generally useful
environment variables (on Linux) that can help when debugging these
issues.
export LD_TRACE_LOADED_OBJECTS=all
<blockquote>
<div>provides a lot of information, sometimes too much depending on the
setting. Output verbose debugging information about the dynamic
linker. If set to <tt class="docutils literal">all</tt> prints all debugging information it has, if
set to <tt class="docutils literal">help</tt> prints a help message about which categories can be
specified in this environment variable</div></blockquote>
export LD_VERBOSE=1
<blockquote>
<div>(glibc since 2.1) If set to a nonempty string, output symbol
versioning information about the program if querying information
about the program (i.e., either <tt class="docutils literal">LD_TRACE_LOADED_OBJECTS</tt> has been set,
or <tt class="docutils literal">--list</tt> or <tt class="docutils literal">--verify</tt> options have been given to the dynamic
linker).</div></blockquote>
export LD_WARN=1
<blockquote>
<div>(ELF only)(glibc since 2.1.3) If set to a nonempty string, warn
about unresolved symbols.</div></blockquote>
</div>
<div class="section" id="ffi-verify-in-line-api-mode">
<h2><a class="toc-backref" href="#id15">ffi.verify(): in-line API-mode</a><a class="headerlink" href="#ffi-verify-in-line-api-mode" title="Permalink to this headline">¶</a></h2>
ffi.verify() is supported for backward compatibility, but is
deprecated. <tt class="docutils literal">ffi.verify(c_header_source, tmpdir=.., ext_package=..,
modulename=.., flags=.., **kwargs)</tt> makes and compiles a C file from
the <tt class="docutils literal">ffi.cdef()</tt>, like <tt class="docutils literal">ffi.set_source()</tt> in API mode, and then
immediately loads and returns the dynamic library object. Some
non-trivial logic is used to decide if the dynamic library must be
recompiled or not; see below for ways to control it.
The <tt class="docutils literal">c_header_source</tt> and the extra keyword arguments have the
same meaning as in <tt class="docutils literal">ffi.set_source()</tt>.
One remaining use case for <tt class="docutils literal">ffi.verify()</tt> would be the following
hack to find explicitly the size of any type, in bytes, and have it
available in Python immediately (e.g. because it is needed in order to
write the rest of the build script):
<div class="highlight-python"><div class="highlight"><pre>ffi = cffi.FFI()
ffi.cdef(&quot;const int mysize;&quot;)
lib = ffi.verify(&quot;const int mysize = sizeof(THE_TYPE);&quot;)
print lib.mysize
</pre></div>
</div>
Extra arguments to <tt class="docutils literal">ffi.verify()</tt>:
<ul>
<li><tt class="docutils literal">tmpdir</tt> controls where the C
files are created and compiled. Unless the <tt class="docutils literal">CFFI_TMPDIR</tt> environment
variable is set, the default is
<tt class="docutils literal">directory_containing_the_py_file/__pycache__</tt> using the
directory name of the .py file that contains the actual call to
<tt class="docutils literal">ffi.verify()</tt>. (This is a bit of a hack but is generally
consistent with the location of the .pyc files for your library.
The name <tt class="docutils literal">__pycache__</tt> itself comes from Python 3.)
</li>
<li><tt class="docutils literal">ext_package</tt> controls in which package the
compiled extension module should be looked from. This is
only useful after distributing ffi.verify()-based modules.
</li>
<li>The <tt class="docutils literal">tag</tt> argument gives an extra string inserted in the
middle of the extension module&#8217;s name: <tt class="docutils literal">_cffi_&lt;tag&gt;_&lt;hash&gt;</tt>.
Useful to give a bit more context, e.g. when debugging.
</li>
<li>The <tt class="docutils literal">modulename</tt> argument can be used to force a specific module
name, overriding the name <tt class="docutils literal">_cffi_&lt;tag&gt;_&lt;hash&gt;</tt>. Use with care,
e.g. if you are passing variable information to <tt class="docutils literal">verify()</tt> but
still want the module name to be always the same (e.g. absolute
paths to local files). In this case, no hash is computed and if
the module name already exists it will be reused without further
check. Be sure to have other means of clearing the <tt class="docutils literal">tmpdir</tt>
whenever you change your sources.
</li>
<li><tt class="docutils literal">source_extension</tt> has the same meaning as in <tt class="docutils literal">ffi.set_source()</tt>.
</li>
<li>The optional <tt class="docutils literal">flags</tt> argument has been added in version 0.9;
see <tt class="docutils literal">man dlopen</tt>
(ignored on Windows). It defaults to <tt class="docutils literal">ffi.RTLD_NOW</tt>. (With
<tt class="docutils literal">ffi.set_source()</tt>, you would use <tt class="docutils literal">sys.setdlopenflags()</tt>.)
</li>
<li>The optional <tt class="docutils literal">relative_to</tt> argument is useful if you need to list
local files passed to the C compiler:
<div class="highlight-python"><div class="highlight"><pre>ext = ffi.verify(..., sources=[&#39;foo.c&#39;], relative_to=__file__)
</pre></div>
</div>
The line above is roughly the same as:
<div class="highlight-python"><div class="highlight"><pre>ext = ffi.verify(..., sources=[&#39;/path/to/this/file/foo.c&#39;])
</pre></div>
</div>
except that the default name of the produced library is built from
the CRC checkum of the argument <tt class="docutils literal">sources</tt>, as well as most other
arguments you give to <tt class="docutils literal">ffi.verify()</tt> &#8211; but not <tt class="docutils literal">relative_to</tt>.
So if you used the second line, it would stop finding the
already-compiled library after your project is installed, because
the <tt class="docutils literal">'/path/to/this/file'</tt> suddenly changed. The first line does
not have this problem.
</li>
</ul>
Note that during development, every time you change the C sources that
you pass to <tt class="docutils literal">cdef()</tt> or <tt class="docutils literal">verify()</tt>, then the latter will create a
new module file name, based on two CRC32 hashes computed from these
strings. This creates more and more files in the <tt class="docutils literal">__pycache__</tt>
directory. It is recommended that you clean it up from time to time.
A nice way to do that is to add, in your test suite, a call to
<tt class="docutils literal">cffi.verifier.cleanup_tmpdir()</tt>. Alternatively, you can manually
remove the whole <tt class="docutils literal">__pycache__</tt> directory.
An alternative cache directory can be given as the <tt class="docutils literal">tmpdir</tt> argument
to <tt class="docutils literal">verify()</tt>, via the environment variable <tt class="docutils literal">CFFI_TMPDIR</tt>, or by
calling <tt class="docutils literal">cffi.verifier.set_tmpdir(path)</tt> prior to calling
<tt class="docutils literal">verify</tt>.
</div>
<div class="section" id="upgrading-from-cffi-0-9-to-cffi-1-0">
<h2><a class="toc-backref" href="#id16">Upgrading from CFFI 0.9 to CFFI 1.0</a><a class="headerlink" href="#upgrading-from-cffi-0-9-to-cffi-1-0" title="Permalink to this headline">¶</a></h2>
CFFI 1.0 is backward-compatible, but it is still a good idea to
consider moving to the out-of-line approach new in 1.0. Here are the
steps.
ABI mode if your CFFI project uses <tt class="docutils literal">ffi.dlopen()</tt>:
<div class="highlight-python"><div class="highlight"><pre>import cffi

ffi = cffi.FFI()
ffi.cdef(&quot;stuff&quot;)
lib = ffi.verify(&quot;real C code&quot;)
</pre></div>
</div>
then you should really rewrite it as described in <a class="reference internal" href="#out-of-line-api">the out-of-line,
API mode</a> above. It avoids a number of issues that have caused
<tt class="docutils literal">ffi.verify()</tt> to grow a number of extra arguments over time. Then
see the <a class="reference internal" href="#distutils-setuptools">distutils or setuptools</a> paragraph. Also, remember to
remove the <tt class="docutils literal">ext_package=&quot;..&quot;</tt> from your <tt class="docutils literal">setup.py</tt>, which was
sometimes needed with <tt class="docutils literal">verify()</tt> but is just creating confusion with
<tt class="docutils literal">set_source()</tt>.
The following example should work both with old (pre-1.0) and new
versions of CFFI&#8212;supporting both is important to run on PyPy,
because CFFI 1.0 does not work in PyPy &lt; 2.6:
<div class="highlight-python"><div class="highlight"><pre># in a separate file &quot;package/foo_build.py&quot;
import cffi

if hasattr(ffi, &#39;set_source&#39;):
 ffi.set_source(&quot;package._foo&quot;, C_HEADER_SRC, **C_KEYWORDS)

ffi.cdef(&#39;&#39;&#39;
 int foo(int);
&#39;&#39;&#39;)

if __name__ == &quot;__main__&quot;:
 ffi.compile()
</pre></div>
</div>
And in the main program:
<div class="highlight-python"><div class="highlight"><pre>try:
 from package._foo import ffi, lib
except ImportError:
 from package.foo_build import ffi, C_HEADER_SRC, C_KEYWORDS
 lib = ffi.verify(C_HEADER_SRC, **C_KEYWORDS)
</pre></div>
</div>
(FWIW, this latest trick can be used more generally to allow the
import to &#8220;work&#8221; even if the <tt class="docutils literal">_foo</tt> module was not generated.)
Writing a <tt class="docutils literal">setup.py</tt> script that works both with CFFI 0.9 and 1.0
requires explicitly checking the version of CFFI that we can have&#8212;it
is hard-coded as a built-in module in PyPy:
<div class="highlight-python"><div class="highlight"><pre>if &#39;_cffi_backend&#39; in sys.builtin_module_names: # PyPy
 import _cffi_backend
 requires_cffi = &quot;cffi==&quot; + _cffi_backend.__version__
else:
 requires_cffi = &quot;cffi&gt;=1.0.0&quot;
</pre></div>
</div>
Then we use the <tt class="docutils literal">requires_cffi</tt> variable to give different arguments to
<tt class="docutils literal">setup()</tt> as needed, e.g.:
<div class="highlight-python"><div class="highlight"><pre>if requires_cffi.startswith(&quot;cffi==0.&quot;):
 # backward compatibility: we have &quot;cffi==0.*&quot;
 from package.foo_build import ffi
 extra_args = dict(
 ext_modules=[ffi.verifier.get_extension()],
 ext_packages=&quot;...&quot;, # if needed
 )
else:
 extra_args = dict(
 setup_requires=[requires_cffi],
 cffi_modules=[&#39;package/foo_build.py:ffi&#39;],
 )
setup(
 name=...,
 ...,
 install_requires=[requires_cffi],
 **extra_args
)
</pre></div>
</div>
</div>
</div>

</div>
 </div>
 </div>
 <div class="sphinxsidebar">
 <div class="sphinxsidebarwrapper">
 <h3><a href="index.html">Table Of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">Preparing and Distributing modules</a><ul>
<li><a class="reference internal" href="#ffi-cdef-declaring-types-and-functions">ffi.cdef(): declaring types and functions</a></li>
<li><a class="reference internal" href="#ffi-dlopen-loading-libraries-in-abi-mode">ffi.dlopen(): loading libraries in ABI mode</a></li>
<li><a class="reference internal" href="#ffi-set-source-preparing-out-of-line-modules">ffi.set_source(): preparing out-of-line modules</a></li>
<li><a class="reference internal" href="#letting-the-c-compiler-fill-the-gaps">Letting the C compiler fill the gaps</a></li>
<li><a class="reference internal" href="#ffi-compile-etc-compiling-out-of-line-modules">ffi.compile() etc.: compiling out-of-line modules</a></li>
<li><a class="reference internal" href="#ffi-include-combining-multiple-cffi-interfaces">ffi.include(): combining multiple CFFI interfaces</a></li>
<li><a class="reference internal" href="#ffi-cdef-limitations">ffi.cdef() limitations</a></li>
<li><a class="reference internal" href="#debugging-dlopen-ed-c-libraries">Debugging dlopen&#8217;ed C libraries</a></li>
<li><a class="reference internal" href="#ffi-verify-in-line-api-mode">ffi.verify(): in-line API-mode</a></li>
<li><a class="reference internal" href="#upgrading-from-cffi-0-9-to-cffi-1-0">Upgrading from CFFI 0.9 to CFFI 1.0</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="ref.html"
 title="previous chapter">CFFI Reference</a>
 <h4>Next topic</h4>
 <a href="embedding.html"
 title="next chapter">Using CFFI for embedding</a>
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/cdef.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
<div id="searchbox" style="display: none">
 <h3>Quick search</h3>
 <form class="search" action="search.html" method="get">
 <input type="text" name="q" />
 <input type="submit" value="Go" />
 <input type="hidden" name="check_keywords" value="yes" />
 <input type="hidden" name="area" value="default" />
 </form>
 
 Enter search terms or a module, class or function name.
 
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="embedding.html" title="Using CFFI for embedding"
 >next</a> |</li>
 <li class="right" >
 <a href="ref.html" title="CFFI Reference"
 >previous</a> |</li>
 <li><a href="index.html">CFFI 1.6.0 documentation</a> &raquo;</li> 
 </ul>
 </div>
 <div class="footer">
 &copy; Copyright 2012-2015, Armin Rigo, Maciej Fijalkowski.
 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
 </div>
 </body>
</html>