EVOLUTION-MANAGER

Edit File: using.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>Using the ffi/lib objects &mdash; CFFI 1.9.1 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.9.1',
 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.9.1 documentation" href="index.html" />
 <link rel="next" title="CFFI Reference" href="ref.html" />
 <link rel="prev" title="Overview" href="overview.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="ref.html" title="CFFI Reference"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="overview.html" title="Overview"
 accesskey="P">previous</a> |</li>
 <li><a href="index.html">CFFI 1.9.1 documentation</a> &raquo;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body">
 
 <div class="section" id="using-the-ffi-lib-objects">
<h1><a class="toc-backref" href="#id12">Using the ffi/lib objects</a><a class="headerlink" href="#using-the-ffi-lib-objects" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
Contents
<ul class="simple">
<li><a class="reference internal" href="#using-the-ffi-lib-objects" id="id12">Using the ffi/lib objects</a><ul>
<li><a class="reference internal" href="#working-with-pointers-structures-and-arrays" id="id13">Working with pointers, structures and arrays</a></li>
<li><a class="reference internal" href="#python-3-support" id="id14">Python 3 support</a></li>
<li><a class="reference internal" href="#an-example-of-calling-a-main-like-thing" id="id15">An example of calling a main-like thing</a></li>
<li><a class="reference internal" href="#function-calls" id="id16">Function calls</a></li>
<li><a class="reference internal" href="#variadic-function-calls" id="id17">Variadic function calls</a></li>
<li><a class="reference internal" href="#extern-python-new-style-callbacks" id="id18">Extern &#8220;Python&#8221; (new-style callbacks)</a><ul>
<li><a class="reference internal" href="#extern-python-and-void-arguments" id="id19">Extern &#8220;Python&#8221; and <tt class="docutils literal">void *</tt> arguments</a></li>
<li><a class="reference internal" href="#extern-python-accessed-from-c-directly" id="id20">Extern &#8220;Python&#8221; accessed from C directly</a></li>
<li><a class="reference internal" href="#extern-python-c" id="id21">Extern &#8220;Python+C&#8221;</a></li>
<li><a class="reference internal" href="#extern-python-reference" id="id22">Extern &#8220;Python&#8221;: reference</a></li>
</ul>
</li>
<li><a class="reference internal" href="#callbacks-old-style" id="id23">Callbacks (old style)</a></li>
<li><a class="reference internal" href="#windows-calling-conventions" id="id24">Windows: calling conventions</a></li>
<li><a class="reference internal" href="#ffi-interface" id="id25">FFI Interface</a></li>
</ul>
</li>
</ul>
</div>
Keep this page under your pillow.
<div class="section" id="working-with-pointers-structures-and-arrays">
<h2><a class="toc-backref" href="#id13">Working with pointers, structures and arrays</a><a class="headerlink" href="#working-with-pointers-structures-and-arrays" title="Permalink to this headline">¶</a></h2>
The C code&#8217;s integers and floating-point values are mapped to Python&#8217;s
regular <tt class="docutils literal">int</tt>, <tt class="docutils literal">long</tt> and <tt class="docutils literal">float</tt>. Moreover, the C type <tt class="docutils literal">char</tt>
corresponds to single-character strings in Python. (If you want it to
map to small integers, use either <tt class="docutils literal">signed char</tt> or <tt class="docutils literal">unsigned char</tt>.)
Similarly, the C type <tt class="docutils literal">wchar_t</tt> corresponds to single-character
unicode strings. Note that in some situations (a narrow Python build
with an underlying 4-bytes wchar_t type), a single wchar_t character
may correspond to a pair of surrogates, which is represented as a
unicode string of length 2. If you need to convert such a 2-chars
unicode string to an integer, <tt class="docutils literal">ord(x)</tt> does not work; use instead
<tt class="docutils literal">int(ffi.cast('wchar_t', x))</tt>.
Pointers, structures and arrays are more complex: they don&#8217;t have an
obvious Python equivalent. Thus, they correspond to objects of type
<tt class="docutils literal">cdata</tt>, which are printed for example as
<tt class="docutils literal">&lt;cdata 'struct foo_s *' 0xa3290d8&gt;</tt>.
<tt class="docutils literal">ffi.new(ctype, [initializer])</tt>: this function builds and returns a
new cdata object of the given <tt class="docutils literal">ctype</tt>. The ctype is usually some
constant string describing the C type. It must be a pointer or array
type. If it is a pointer, e.g. <tt class="docutils literal">&quot;int *&quot;</tt> or <tt class="docutils literal">struct foo *</tt>, then
it allocates the memory for one <tt class="docutils literal">int</tt> or <tt class="docutils literal">struct foo</tt>. If it is
an array, e.g. <tt class="docutils literal">int[10]</tt>, then it allocates the memory for ten
<tt class="docutils literal">int</tt>. In both cases the returned cdata is of type <tt class="docutils literal">ctype</tt>.
The memory is initially filled with zeros. An initializer can be given
too, as described later.
Example:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; ffi.new(&quot;int *&quot;)
&lt;cdata &#39;int *&#39; owning 4 bytes&gt;
&gt;&gt;&gt; ffi.new(&quot;int[10]&quot;)
&lt;cdata &#39;int[10]&#39; owning 40 bytes&gt;

&gt;&gt;&gt; ffi.new(&quot;char *&quot;) # allocates only one char---not a C string!
&lt;cdata &#39;char *&#39; owning 1 bytes&gt;
&gt;&gt;&gt; ffi.new(&quot;char[]&quot;, &quot;foobar&quot;) # this allocates a C string, ending in \0
&lt;cdata &#39;char[]&#39; owning 7 bytes&gt;
</pre></div>
</div>
Unlike C, the returned pointer object has ownership on the allocated
memory: when this exact object is garbage-collected, then the memory is
freed. If, at the level of C, you store a pointer to the memory
somewhere else, then make sure you also keep the object alive for as
long as needed. (This also applies if you immediately cast the returned
pointer to a pointer of a different type: only the original object has
ownership, so you must keep it alive. As soon as you forget it, then
the casted pointer will point to garbage! In other words, the ownership
rules are attached to the wrapper cdata objects: they are not, and
cannot, be attached to the underlying raw memory.) Example:
<div class="highlight-python"><div class="highlight"><pre>global_weakkeydict = weakref.WeakKeyDictionary()

def make_foo():
 s1 = ffi.new(&quot;struct foo *&quot;)
 fld1 = ffi.new(&quot;struct bar *&quot;)
 fld2 = ffi.new(&quot;struct bar *&quot;)
 s1.thefield1 = fld1
 s1.thefield2 = fld2
 # here the &#39;fld1&#39; and &#39;fld2&#39; object must not go away,
 # otherwise &#39;s1.thefield1/2&#39; will point to garbage!
 global_weakkeydict[s1] = (fld1, fld2)
 # now &#39;s1&#39; keeps alive &#39;fld1&#39; and &#39;fld2&#39;. When &#39;s1&#39; goes
 # away, then the weak dictionary entry will be removed.
 return s1
</pre></div>
</div>
Usually you don&#8217;t need a weak dict: for example, to call a function with
a <tt class="docutils literal">char * *</tt> argument that contains a pointer to a <tt class="docutils literal">char *</tt> pointer,
it is enough to do this:
<div class="highlight-python"><div class="highlight"><pre>p = ffi.new(&quot;char[]&quot;, &quot;hello, world&quot;) # p is a &#39;char *&#39;
q = ffi.new(&quot;char **&quot;, p) # q is a &#39;char **&#39;
lib.myfunction(q)
# p is alive at least until here, so that&#39;s fine
</pre></div>
</div>
However, this is always wrong (usage of freed memory):
<div class="highlight-python"><div class="highlight"><pre>p = ffi.new(&quot;char **&quot;, ffi.new(&quot;char[]&quot;, &quot;hello, world&quot;))
# WRONG! as soon as p is built, the inner ffi.new() gets freed!
</pre></div>
</div>
This is wrong too, for the same reason:
<div class="highlight-python"><div class="highlight"><pre>p = ffi.new(&quot;struct my_stuff&quot;)
p.foo = ffi.new(&quot;char[]&quot;, &quot;hello, world&quot;)
# WRONG! as soon as p.foo is set, the ffi.new() gets freed!
</pre></div>
</div>
The cdata objects support mostly the same operations as in C: you can
read or write from pointers, arrays and structures. Dereferencing a
pointer is done usually in C with the syntax <tt class="docutils literal">*p</tt>, which is not valid
Python, so instead you have to use the alternative syntax <tt class="docutils literal">p[0]</tt>
(which is also valid C). Additionally, the <tt class="docutils literal">p.x</tt> and <tt class="docutils literal">p-&gt;x</tt>
syntaxes in C both become <tt class="docutils literal">p.x</tt> in Python.
We have <tt class="docutils literal">ffi.NULL</tt> to use in the same places as the C <tt class="docutils literal">NULL</tt>.
Like the latter, it is actually defined to be <tt class="docutils literal">ffi.cast(&quot;void *&quot;,
0)</tt>. For example, reading a NULL pointer returns a <tt class="docutils literal">&lt;cdata 'type *'
NULL&gt;</tt>, which you can check for e.g. by comparing it with
<tt class="docutils literal">ffi.NULL</tt>.
There is no general equivalent to the <tt class="docutils literal">&amp;</tt> operator in C (because it
would not fit nicely in the model, and it does not seem to be needed
here). But see <a class="reference external" href="ref.html#ffi-addressof">ffi.addressof()</a>.
Any operation that would in C return a pointer or array or struct type
gives you a fresh cdata object. Unlike the &#8220;original&#8221; one, these fresh
cdata objects don&#8217;t have ownership: they are merely references to
existing memory.
As an exception to the above rule, dereferencing a pointer that owns a
struct or union object returns a cdata struct or union object
that &#8220;co-owns&#8221; the same memory. Thus in this case there are two
objects that can keep the same memory alive. This is done for cases where
you really want to have a struct object but don&#8217;t have any convenient
place to keep alive the original pointer object (returned by
<tt class="docutils literal">ffi.new()</tt>).
Example:
<div class="highlight-python"><div class="highlight"><pre># void somefunction(int *);

x = ffi.new(&quot;int *&quot;) # allocate one int, and return a pointer to it
x[0] = 42 # fill it
lib.somefunction(x) # call the C function
print x[0] # read the possibly-changed value
</pre></div>
</div>
The equivalent of C casts are provided with <tt class="docutils literal">ffi.cast(&quot;type&quot;, value)</tt>.
They should work in the same cases as they do in C. Additionally, this
is the only way to get cdata objects of integer or floating-point type:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; x = ffi.cast(&quot;int&quot;, 42)
&gt;&gt;&gt; x
&lt;cdata &#39;int&#39; 42&gt;
&gt;&gt;&gt; int(x)
42
</pre></div>
</div>
To cast a pointer to an int, cast it to <tt class="docutils literal">intptr_t</tt> or <tt class="docutils literal">uintptr_t</tt>,
which are defined by C to be large enough integer types (example on 32
bits):
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; int(ffi.cast(&quot;intptr_t&quot;, pointer_cdata)) # signed
-1340782304
&gt;&gt;&gt; int(ffi.cast(&quot;uintptr_t&quot;, pointer_cdata)) # unsigned
2954184992L
</pre></div>
</div>
The initializer given as the optional second argument to <tt class="docutils literal">ffi.new()</tt>
can be mostly anything that you would use as an initializer for C code,
with lists or tuples instead of using the C syntax <tt class="docutils literal">{ .., .., .. }</tt>.
Example:
<div class="highlight-python"><pre>typedef struct { int x, y; } foo_t;

foo_t v = { 1, 2 };            // C syntax
v = ffi.new("foo_t *", [1, 2]) # CFFI equivalent

foo_t v = { .y=1, .x=2 }; // C99 syntax
v = ffi.new("foo_t *", {'y': 1, 'x': 2}) # CFFI equivalent</pre>
</div>
Like C, arrays of chars can also be initialized from a string, in
which case a terminating null character is appended implicitly:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; x = ffi.new(&quot;char[]&quot;, &quot;hello&quot;)
&gt;&gt;&gt; x
&lt;cdata &#39;char[]&#39; owning 6 bytes&gt;
&gt;&gt;&gt; len(x) # the actual size of the array
6
&gt;&gt;&gt; x[5] # the last item in the array
&#39;\x00&#39;
&gt;&gt;&gt; x[0] = &#39;H&#39; # change the first item
&gt;&gt;&gt; ffi.string(x) # interpret &#39;x&#39; as a regular null-terminated string
&#39;Hello&#39;
</pre></div>
</div>
Similarly, arrays of wchar_t can be initialized from a unicode string,
and calling <tt class="docutils literal">ffi.string()</tt> on the cdata object returns the current unicode
string stored in the wchar_t array (adding surrogates if necessary).
Note that unlike Python lists or tuples, but like C, you cannot index in
a C array from the end using negative numbers.
More generally, the C array types can have their length unspecified in C
types, as long as their length can be derived from the initializer, like
in C:
<div class="highlight-python"><pre>int array[] = { 1, 2, 3, 4 }; // C syntax
array = ffi.new("int[]", [1, 2, 3, 4]) # CFFI equivalent</pre>
</div>
As an extension, the initializer can also be just a number, giving
the length (in case you just want zero-initialization):
<div class="highlight-python"><pre>int array[1000]; // C syntax
array = ffi.new("int[1000]") # CFFI 1st equivalent
array = ffi.new("int[]", 1000) # CFFI 2nd equivalent</pre>
</div>
This is useful if the length is not actually a constant, to avoid things
like <tt class="docutils literal">ffi.new(&quot;int[%d]&quot; % x)</tt>. Indeed, this is not recommended:
<tt class="docutils literal">ffi</tt> normally caches the string <tt class="docutils literal">&quot;int[]&quot;</tt> to not need to re-parse
it all the time.
The C99 variable-sized structures are supported too, as long as the
initializer says how long the array should be:
<div class="highlight-python"><div class="highlight"><pre># typedef struct { int x; int y[]; } foo_t;

p = ffi.new(&quot;foo_t *&quot;, [5, [6, 7, 8]]) # length 3
p = ffi.new(&quot;foo_t *&quot;, [5, 3]) # length 3 with 0 in the array
p = ffi.new(&quot;foo_t *&quot;, {&#39;y&#39;: 3}) # length 3 with 0 everywhere
</pre></div>
</div>
Finally, note that any Python object used as initializer can also be
used directly without <tt class="docutils literal">ffi.new()</tt> in assignments to array items or
struct fields. In fact, <tt class="docutils literal">p = ffi.new(&quot;T*&quot;, initializer)</tt> is
equivalent to <tt class="docutils literal">p = ffi.new(&quot;T*&quot;); p[0] = initializer</tt>. Examples:
<div class="highlight-python"><div class="highlight"><pre># if &#39;p&#39; is a &lt;cdata &#39;int[5][5]&#39;&gt;
p[2] = [10, 20] # writes to p[2][0] and p[2][1]

# if &#39;p&#39; is a &lt;cdata &#39;foo_t *&#39;&gt;, and foo_t has fields x, y and z
p[0] = {&#39;x&#39;: 10, &#39;z&#39;: 20} # writes to p.x and p.z; p.y unmodified

# if, on the other hand, foo_t has a field &#39;char a[5]&#39;:
p.a = &quot;abc&quot; # writes &#39;a&#39;, &#39;b&#39;, &#39;c&#39; and &#39;\0&#39;; p.a[4] unmodified
</pre></div>
</div>
In function calls, when passing arguments, these rules can be used too;
see <a class="reference internal" href="#function-calls">Function calls</a>.
</div>
<div class="section" id="python-3-support">
<h2><a class="toc-backref" href="#id14">Python 3 support</a><a class="headerlink" href="#python-3-support" title="Permalink to this headline">¶</a></h2>
Python 3 is supported, but the main point to note is that the <tt class="docutils literal">char</tt> C
type corresponds to the <tt class="docutils literal">bytes</tt> Python type, and not <tt class="docutils literal">str</tt>. It is
your responsibility to encode/decode all Python strings to bytes when
passing them to or receiving them from CFFI.
This only concerns the <tt class="docutils literal">char</tt> type and derivative types; other parts
of the API that accept strings in Python 2 continue to accept strings in
Python 3.
</div>
<div class="section" id="an-example-of-calling-a-main-like-thing">
<h2><a class="toc-backref" href="#id15">An example of calling a main-like thing</a><a class="headerlink" href="#an-example-of-calling-a-main-like-thing" title="Permalink to this headline">¶</a></h2>
Imagine we have something like this:
<div class="highlight-python"><div class="highlight"><pre>from cffi import FFI
ffi = FFI()
ffi.cdef(&quot;&quot;&quot;
 int main_like(int argv, char *argv[]);
&quot;&quot;&quot;)
lib = ffi.dlopen(&quot;some_library.so&quot;)
</pre></div>
</div>
Now, everything is simple, except, how do we create the <tt class="docutils literal">char**</tt> argument
here?
The first idea:
<div class="highlight-python"><div class="highlight"><pre>lib.main_like(2, [&quot;arg0&quot;, &quot;arg1&quot;])
</pre></div>
</div>
does not work, because the initializer receives two Python <tt class="docutils literal">str</tt> objects
where it was expecting <tt class="docutils literal">&lt;cdata 'char *'&gt;</tt> objects. You need to use
<tt class="docutils literal">ffi.new()</tt> explicitly to make these objects:
<div class="highlight-python"><div class="highlight"><pre>lib.main_like(2, [ffi.new(&quot;char[]&quot;, &quot;arg0&quot;),
 ffi.new(&quot;char[]&quot;, &quot;arg1&quot;)])
</pre></div>
</div>
Note that the two <tt class="docutils literal">&lt;cdata 'char[]'&gt;</tt> objects are kept alive for the
duration of the call: they are only freed when the list itself is freed,
and the list is only freed when the call returns.
If you want instead to build an &#8220;argv&#8221; variable that you want to reuse,
then more care is needed:
<div class="highlight-python"><div class="highlight"><pre># DOES NOT WORK!
argv = ffi.new(&quot;char *[]&quot;, [ffi.new(&quot;char[]&quot;, &quot;arg0&quot;),
 ffi.new(&quot;char[]&quot;, &quot;arg1&quot;)])
</pre></div>
</div>
In the above example, the inner &#8220;arg0&#8221; string is deallocated as soon
as &#8220;argv&#8221; is built. You have to make sure that you keep a reference
to the inner &#8220;char[]&#8221; objects, either directly or by keeping the list
alive like this:
<div class="highlight-python"><div class="highlight"><pre>argv_keepalive = [ffi.new(&quot;char[]&quot;, &quot;arg0&quot;),
 ffi.new(&quot;char[]&quot;, &quot;arg1&quot;)]
argv = ffi.new(&quot;char *[]&quot;, argv_keepalive)
</pre></div>
</div>
</div>
<div class="section" id="function-calls">
<h2><a class="toc-backref" href="#id16">Function calls</a><a class="headerlink" href="#function-calls" title="Permalink to this headline">¶</a></h2>
When calling C functions, passing arguments follows mostly the same
rules as assigning to structure fields, and the return value follows the
same rules as reading a structure field. For example:
<div class="highlight-python"><div class="highlight"><pre># int foo(short a, int b);

n = lib.foo(2, 3) # returns a normal integer
lib.foo(40000, 3) # raises OverflowError
</pre></div>
</div>
You can pass to <tt class="docutils literal">char *</tt> arguments a normal Python string (but don&#8217;t
pass a normal Python string to functions that take a <tt class="docutils literal">char *</tt>
argument and may mutate it!):
<div class="highlight-python"><div class="highlight"><pre># size_t strlen(const char *);

assert lib.strlen(&quot;hello&quot;) == 5
</pre></div>
</div>
You can also pass unicode strings as <tt class="docutils literal">wchar_t *</tt> arguments. Note that
the C language makes no difference between argument declarations that
use <tt class="docutils literal">type *</tt> or <tt class="docutils literal">type[]</tt>. For example, <tt class="docutils literal">int *</tt> is fully
equivalent to <tt class="docutils literal">int[]</tt> (or even <tt class="docutils literal">int[5]</tt>; the 5 is ignored). For CFFI,
this means that you can always pass arguments that can be converted to
either <tt class="docutils literal">int *</tt> or <tt class="docutils literal">int[]</tt>. For example:
<div class="highlight-python"><div class="highlight"><pre># void do_something_with_array(int *array);

lib.do_something_with_array([1, 2, 3, 4, 5]) # works for int[]
</pre></div>
</div>
See <a class="reference external" href="ref.html#conversions">Reference: conversions</a> for a similar way to pass <tt class="docutils literal">struct foo_s
*</tt> arguments&#8212;but in general, it is clearer in this case to pass
<tt class="docutils literal">ffi.new('struct foo_s *', initializer)</tt>.
CFFI supports passing and returning structs and unions to functions and
callbacks. Example:
<div class="highlight-python"><div class="highlight"><pre># struct foo_s { int a, b; };
# struct foo_s function_returning_a_struct(void);

myfoo = lib.function_returning_a_struct()
# `myfoo`: &lt;cdata &#39;struct foo_s&#39; owning 8 bytes&gt;
</pre></div>
</div>
For performance, non-variadic API-level functions that you get by
writing <tt class="docutils literal">lib.some_function</tt> are not <tt class="docutils literal">&lt;cdata&gt;</tt>
objects, but an object of a different type (on CPython, <tt class="docutils literal">&lt;built-in
function&gt;</tt>). This means you cannot pass them directly to some other C
function expecting a function pointer argument. Only <tt class="docutils literal">ffi.typeof()</tt>
works on them. To get a cdata containing a regular function pointer,
use <tt class="docutils literal">ffi.addressof(lib, &quot;name&quot;)</tt>.
There are a few (obscure) limitations to the supported argument and
return types. These limitations come from libffi and apply only to
calling <tt class="docutils literal">&lt;cdata&gt;</tt> function pointers; in other words, they don&#8217;t
apply to non-variadic <tt class="docutils literal">cdef()</tt>-declared functions if you are using
the API mode. The limitations are that you cannot pass directly as
argument or return type:
<ul class="simple">
<li>a union (but a pointer to a union is fine);</li>
<li>a struct which uses bitfields (but a pointer to such a struct is
fine);</li>
<li>a struct that was declared with &#8220;<tt class="docutils literal">...</tt>&#8221; in the <tt class="docutils literal">cdef()</tt>.</li>
</ul>
In API mode, you can work around these limitations: for example, if you
need to call such a function pointer from Python, you can instead write
a custom C function that accepts the function pointer and the real
arguments and that does the call from C. Then declare that custom C
function in the <tt class="docutils literal">cdef()</tt> and use it from Python.
</div>
<div class="section" id="variadic-function-calls">
<h2><a class="toc-backref" href="#id17">Variadic function calls</a><a class="headerlink" href="#variadic-function-calls" title="Permalink to this headline">¶</a></h2>
Variadic functions in C (which end with &#8220;<tt class="docutils literal">...</tt>&#8221; as their last
argument) can be declared and called normally, with the exception that
all the arguments passed in the variable part must be cdata objects.
This is because it would not be possible to guess, if you wrote this:
<div class="highlight-python"><div class="highlight"><pre>lib.printf(&quot;hello, %d\n&quot;, 42) # doesn&#39;t work!
</pre></div>
</div>
that you really meant the 42 to be passed as a C <tt class="docutils literal">int</tt>, and not a
<tt class="docutils literal">long</tt> or <tt class="docutils literal">long long</tt>. The same issue occurs with <tt class="docutils literal">float</tt> versus
<tt class="docutils literal">double</tt>. So you have to force cdata objects of the C type you want,
if necessary with <tt class="docutils literal">ffi.cast()</tt>:
<div class="highlight-python"><div class="highlight"><pre>lib.printf(&quot;hello, %d\n&quot;, ffi.cast(&quot;int&quot;, 42))
lib.printf(&quot;hello, %ld\n&quot;, ffi.cast(&quot;long&quot;, 42))
lib.printf(&quot;hello, %f\n&quot;, ffi.cast(&quot;double&quot;, 42))
</pre></div>
</div>
But of course:
<div class="highlight-python"><div class="highlight"><pre>lib.printf(&quot;hello, %s\n&quot;, ffi.new(&quot;char[]&quot;, &quot;world&quot;))
</pre></div>
</div>
Note that if you are using <tt class="docutils literal">dlopen()</tt>, the function declaration in the
<tt class="docutils literal">cdef()</tt> must match the original one in C exactly, as usual &#8212; in
particular, if this function is variadic in C, then its <tt class="docutils literal">cdef()</tt>
declaration must also be variadic. You cannot declare it in the
<tt class="docutils literal">cdef()</tt> with fixed arguments instead, even if you plan to only call
it with these argument types. The reason is that some architectures
have a different calling convention depending on whether the function
signature is fixed or not. (On x86-64, the difference can sometimes be
seen in PyPy&#8217;s JIT-generated code if some arguments are <tt class="docutils literal">double</tt>.)
Note that the function signature <tt class="docutils literal">int foo();</tt> is interpreted by CFFI
as equivalent to <tt class="docutils literal">int foo(void);</tt>. This differs from the C standard,
in which <tt class="docutils literal">int foo();</tt> is really like <tt class="docutils literal">int foo(...);</tt> and can be
called with any arguments. (This feature of C is a pre-C89 relic: the
arguments cannot be accessed at all in the body of <tt class="docutils literal">foo()</tt> without
relying on compiler-specific extensions. Nowadays virtually all code
with <tt class="docutils literal">int foo();</tt> really means <tt class="docutils literal">int foo(void);</tt>.)
</div>
<div class="section" id="extern-python-new-style-callbacks">
<h2><a class="toc-backref" href="#id18">Extern &#8220;Python&#8221; (new-style callbacks)</a><a class="headerlink" href="#extern-python-new-style-callbacks" title="Permalink to this headline">¶</a></h2>
When the C code needs a pointer to a function which invokes back a
Python function of your choice, here is how you do it in the
out-of-line API mode. The next section about <a class="reference internal" href="#callbacks">Callbacks</a> describes the
ABI-mode solution.
This is new in version 1.4. Use old-style <a class="reference internal" href="#callbacks">Callbacks</a> if backward
compatibility is an issue. (The original callbacks are slower to
invoke and have the same issue as libffi&#8217;s callbacks; notably, see the
<a class="reference internal" href="#callbacks">warning</a>. The new style described in the present section does not
use libffi&#8217;s callbacks at all.)
In the builder script, declare in the cdef a function prefixed with
<tt class="docutils literal">extern &quot;Python&quot;</tt>:
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.cdef(&quot;&quot;&quot;
 extern &quot;Python&quot; int my_callback(int, int);

void library_function(int(*callback)(int, int));
&quot;&quot;&quot;)
ffibuilder.set_source(&quot;_my_example&quot;, r&quot;&quot;&quot;
 #include &lt;some_library.h&gt;
&quot;&quot;&quot;)
</pre></div>
</div>
The function <tt class="docutils literal">my_callback()</tt> is then implemented in Python inside
your application&#8217;s code:
<div class="highlight-python"><div class="highlight"><pre>from _my_example import ffi, lib

@ffi.def_extern()
def my_callback(x, y):
 return 42
</pre></div>
</div>
You obtain a <tt class="docutils literal">&lt;cdata&gt;</tt> pointer-to-function object by getting
<tt class="docutils literal">lib.my_callback</tt>. This <tt class="docutils literal">&lt;cdata&gt;</tt> can be passed to C code and
then works like a callback: when the C code calls this function
pointer, the Python function <tt class="docutils literal">my_callback</tt> is called. (You need
to pass <tt class="docutils literal">lib.my_callback</tt> to C code, and not <tt class="docutils literal">my_callback</tt>: the
latter is just the Python function above, which cannot be passed to C.)
CFFI implements this by defining <tt class="docutils literal">my_callback</tt> as a static C
function, written after the <tt class="docutils literal">set_source()</tt> code. The <tt class="docutils literal">&lt;cdata&gt;</tt>
then points to this function. What this function does is invoke the
Python function object that is, at runtime, attached with
<tt class="docutils literal">&#64;ffi.def_extern()</tt>.
The <tt class="docutils literal">&#64;ffi.def_extern()</tt> decorator should be applied to global
functions, one for each <tt class="docutils literal">extern &quot;Python&quot;</tt> function of the same
name.
To support some corner cases, it is possible to redefine the attached
Python function by calling <tt class="docutils literal">&#64;ffi.def_extern()</tt> again for the same
name&#8212;but this is not recommended! Better attach a single global
Python function for this name, and write it more flexibly in the first
place. This is because each <tt class="docutils literal">extern &quot;Python&quot;</tt> function turns into
only one C function. Calling <tt class="docutils literal">&#64;ffi.def_extern()</tt> again changes this
function&#8217;s C logic to call the new Python function; the old Python
function is not callable any more. The C function pointer you get
from <tt class="docutils literal">lib.my_function</tt> is always this C function&#8217;s address, i.e. it
remains the same.
<div class="section" id="extern-python-and-void-arguments">
<h3><a class="toc-backref" href="#id19">Extern &#8220;Python&#8221; and <tt class="docutils literal">void *</tt> arguments</a><a class="headerlink" href="#extern-python-and-void-arguments" title="Permalink to this headline">¶</a></h3>
As described just before, you cannot use <tt class="docutils literal">extern &quot;Python&quot;</tt> to make a
variable number of C function pointers. However, achieving that
result is not possible in pure C code either. For this reason, it is
usual for C to define callbacks with a <tt class="docutils literal">void *data</tt> argument. You
can use <tt class="docutils literal">ffi.new_handle()</tt> and <tt class="docutils literal">ffi.from_handle()</tt> to pass a
Python object through this <tt class="docutils literal">void *</tt> argument. For example, if the C
type of the callbacks is:
<div class="highlight-python"><pre>typedef void (*event_cb_t)(event_t *evt, void *userdata);</pre>
</div>
and you register events by calling this function:
<div class="highlight-python"><pre>void event_cb_register(event_cb_t cb, void *userdata);</pre>
</div>
Then you would write this in the build script:
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.cdef(&quot;&quot;&quot;
 typedef ... event_t;
 typedef void (*event_cb_t)(event_t *evt, void *userdata);
 void event_cb_register(event_cb_t cb, void *userdata);

extern &quot;Python&quot; void my_event_callback(event_t *, void *);
&quot;&quot;&quot;)
ffibuilder.set_source(&quot;_demo_cffi&quot;, r&quot;&quot;&quot;
 #include &lt;the_event_library.h&gt;
&quot;&quot;&quot;)
</pre></div>
</div>
and in your main application you register events like this:
<div class="highlight-python"><div class="highlight"><pre>from _demo_cffi import ffi, lib

def process_event(self, evt):
 print &quot;got event!&quot;

@ffi.def_extern()
def my_event_callback(evt, userdata):
 widget = ffi.from_handle(userdata)
 widget.process_event(evt)
</pre></div>
</div>
Some other libraries don&#8217;t have an explicit <tt class="docutils literal">void *</tt> argument, but
let you attach the <tt class="docutils literal">void *</tt> to an existing structure. For example,
the library might say that <tt class="docutils literal">widget-&gt;userdata</tt> is a generic field
reserved for the application. If the event&#8217;s signature is now this:
<div class="highlight-python"><pre>typedef void (*event_cb_t)(widget_t *w, event_t *evt);</pre>
</div>
Then you can use the <tt class="docutils literal">void *</tt> field in the low-level
<tt class="docutils literal">widget_t *</tt> like this:
<div class="highlight-python"><div class="highlight"><pre>from _demo_cffi import ffi, lib

class Widget(object):
 def __init__(self):
 ll_widget = lib.new_widget(500, 500)
 self.ll_widget = ll_widget # &lt;cdata &#39;struct widget *&#39;&gt;
 userdata = ffi.new_handle(self)
 self._userdata = userdata # must still keep this alive!
 ll_widget.userdata = userdata # this makes a copy of the &quot;void *&quot;
 lib.event_cb_register(ll_widget, lib.my_event_callback)

@ffi.def_extern()
def my_event_callback(ll_widget, evt):
 widget = ffi.from_handle(ll_widget.userdata)
 widget.process_event(evt)
</pre></div>
</div>
</div>
<div class="section" id="extern-python-accessed-from-c-directly">
<h3><a class="toc-backref" href="#id20">Extern &#8220;Python&#8221; accessed from C directly</a><a class="headerlink" href="#extern-python-accessed-from-c-directly" title="Permalink to this headline">¶</a></h3>
In case you want to access some <tt class="docutils literal">extern &quot;Python&quot;</tt> function directly
from the C code written in <tt class="docutils literal">set_source()</tt>, you need to write a
forward declaration. (By default it needs to be static, but see
<a class="reference internal" href="#extern-python-c">next paragraph</a>.) The real implementation of this function
is added by CFFI after the C code&#8212;this is needed because the
declaration might use types defined by <tt class="docutils literal">set_source()</tt>
(e.g. <tt class="docutils literal">event_t</tt> above, from the <tt class="docutils literal">#include</tt>), so it cannot be
generated before.
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.set_source(&quot;_demo_cffi&quot;, r&quot;&quot;&quot;
 #include &lt;the_event_library.h&gt;

static void my_event_callback(widget_t *, event_t *);

/* here you can write C code which uses &#39;&amp;my_event_callback&#39; */
&quot;&quot;&quot;)
</pre></div>
</div>
This can also be used to write custom C code which calls Python
directly. Here is an example (inefficient in this case, but might be
useful if the logic in <tt class="docutils literal">my_algo()</tt> is much more complex):
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.cdef(&quot;&quot;&quot;
 extern &quot;Python&quot; int f(int);
 int my_algo(int);
&quot;&quot;&quot;)
ffibuilder.set_source(&quot;_example_cffi&quot;, r&quot;&quot;&quot;
 static int f(int); /* the forward declaration */

static int my_algo(int n) {
 int i, sum = 0;
 for (i = 0; i &lt; n; i++)
 sum += f(i); /* call f() here */
 return sum;
 }
&quot;&quot;&quot;)
</pre></div>
</div>
</div>
<div class="section" id="extern-python-c">
<h3><a class="toc-backref" href="#id21">Extern &#8220;Python+C&#8221;</a><a class="headerlink" href="#extern-python-c" title="Permalink to this headline">¶</a></h3>
Functions declared with <tt class="docutils literal">extern &quot;Python&quot;</tt> are generated as
<tt class="docutils literal">static</tt> functions in the C source. However, in some cases it is
convenient to make them non-static, typically when you want to make
them directly callable from other C source files. To do that, you can
say <tt class="docutils literal">extern &quot;Python+C&quot;</tt> instead of just <tt class="docutils literal">extern &quot;Python&quot;</tt>. New
in version 1.6.
<table border="1" class="docutils">
<colgroup>
<col width="49%" />
<col width="51%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>if the cdef contains</td>
<td>then CFFI generates</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal">extern &quot;Python&quot; int f(int);</tt></td>
<td><tt class="docutils literal">static int f(int) { /* code */ }</tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal">extern &quot;Python+C&quot; int f(int);</tt></td>
<td><tt class="docutils literal">int f(int) { /* code */ }</tt></td>
</tr>
</tbody>
</table>
The name <tt class="docutils literal">extern &quot;Python+C&quot;</tt> comes from the fact that we want an
extern function in both senses: as an <tt class="docutils literal">extern &quot;Python&quot;</tt>, and as a
C function that is not static.
You cannot make CFFI generate additional macros or other
compiler-specific stuff like the GCC <tt class="docutils literal">__attribute__</tt>. You can only
control whether the function should be <tt class="docutils literal">static</tt> or not. But often,
these attributes must be written alongside the function header, and
it is fine if the function implementation does not repeat them:
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.cdef(&quot;&quot;&quot;
 extern &quot;Python+C&quot; int f(int); /* not static */
&quot;&quot;&quot;)
ffibuilder.set_source(&quot;_example_cffi&quot;, r&quot;&quot;&quot;
 /* the forward declaration, setting a gcc attribute
 (this line could also be in some .h file, to be included
 both here and in the other C files of the project) */
 int f(int) __attribute__((visibility(&quot;hidden&quot;)));
&quot;&quot;&quot;)
</pre></div>
</div>
</div>
<div class="section" id="extern-python-reference">
<h3><a class="toc-backref" href="#id22">Extern &#8220;Python&#8221;: reference</a><a class="headerlink" href="#extern-python-reference" title="Permalink to this headline">¶</a></h3>
<tt class="docutils literal">extern &quot;Python&quot;</tt> must appear in the cdef(). Like the C++ <tt class="docutils literal">extern
&quot;C&quot;</tt> syntax, it can also be used with braces around a group of
functions:
<div class="highlight-python"><pre>extern "Python" {
 int foo(int);
 int bar(int);
}</pre>
</div>
The <tt class="docutils literal">extern &quot;Python&quot;</tt> functions cannot be variadic for now. This
may be implemented in the future. (<a class="reference external" href="https://bitbucket.org/cffi/cffi/src/default/demo/extern_python_varargs.py">This demo</a> shows how to do it
anyway, but it is a bit lengthy.)
Each corresponding Python callback function is defined with the
<tt class="docutils literal">&#64;ffi.def_extern()</tt> decorator. Be careful when writing this
function: if it raises an exception, or tries to return an object of
the wrong type, then the exception cannot be propagated. Instead, the
exception is printed to stderr and the C-level callback is made to
return a default value. This can be controlled with <tt class="docutils literal">error</tt> and
<tt class="docutils literal">onerror</tt>, described below.
The <tt class="docutils literal">&#64;ffi.def_extern()</tt> decorator takes these optional arguments:
<ul class="simple">
<li><tt class="docutils literal">name</tt>: the name of the function as written in the cdef. By default
it is taken from the name of the Python function you decorate.</li>
</ul>
<ul id="error-onerror">
<li><tt class="docutils literal">error</tt>: the returned value in case the Python function raises an
exception. It is 0 or null by default. The exception is still
printed to stderr, so this should be used only as a last-resort
solution.
</li>
<li><tt class="docutils literal">onerror</tt>: if you want to be sure to catch all exceptions, use
<tt class="docutils literal">&#64;ffi.def_extern(onerror=my_handler)</tt>. If an exception occurs and
<tt class="docutils literal">onerror</tt> is specified, then <tt class="docutils literal">onerror(exception, exc_value,
traceback)</tt> is called. This is useful in some situations where you
cannot simply write <tt class="docutils literal">try: except:</tt> in the main callback function,
because it might not catch exceptions raised by signal handlers: if
a signal occurs while in C, the Python signal handler is called as
soon as possible, which is after entering the callback function but
before executing even the <tt class="docutils literal">try:</tt>. If the signal handler raises,
we are not in the <tt class="docutils literal">try: except:</tt> yet.
If <tt class="docutils literal">onerror</tt> is called and returns normally, then it is assumed
that it handled the exception on its own and nothing is printed to
stderr. If <tt class="docutils literal">onerror</tt> raises, then both tracebacks are printed.
Finally, <tt class="docutils literal">onerror</tt> can itself provide the result value of the
callback in C, but doesn&#8217;t have to: if it simply returns None&#8212;or
if <tt class="docutils literal">onerror</tt> itself fails&#8212;then the value of <tt class="docutils literal">error</tt> will be
used, if any.
Note the following hack: in <tt class="docutils literal">onerror</tt>, you can access the original
callback arguments as follows. First check if <tt class="docutils literal">traceback</tt> is not
None (it is None e.g. if the whole function ran successfully but
there was an error converting the value returned: this occurs after
the call). If <tt class="docutils literal">traceback</tt> is not None, then
<tt class="docutils literal">traceback.tb_frame</tt> is the frame of the outermost function,
i.e. directly the frame of the function decorated with
<tt class="docutils literal">&#64;ffi.def_extern()</tt>. So you can get the value of <tt class="docutils literal">argname</tt> in
that frame by reading <tt class="docutils literal">traceback.tb_frame.f_locals['argname']</tt>.
</li>
</ul>
</div>
</div>
<div class="section" id="callbacks-old-style">
<h2><a class="toc-backref" href="#id23">Callbacks (old style)</a><a class="headerlink" href="#callbacks-old-style" title="Permalink to this headline">¶</a></h2>
Here is how to make a new <tt class="docutils literal">&lt;cdata&gt;</tt> object that contains a pointer
to a function, where that function invokes back a Python function of
your choice:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; @ffi.callback(&quot;int(int, int)&quot;)
&gt;&gt;&gt; def myfunc(x, y):
... return x + y
...
&gt;&gt;&gt; myfunc
&lt;cdata &#39;int(*)(int, int)&#39; calling &lt;function myfunc at 0xf757bbc4&gt;&gt;
</pre></div>
</div>
Note that <tt class="docutils literal">&quot;int(*)(int, int)&quot;</tt> is a C function pointer type, whereas
<tt class="docutils literal">&quot;int(int, int)&quot;</tt> is a C function type. Either can be specified to
ffi.callback() and the result is the same.
<div class="admonition warning">
Warning
Callbacks are provided for the ABI mode or for backward
compatibility. If you are using the out-of-line API mode, it is
recommended to use the <a class="reference internal" href="#id3">extern &#8220;Python&#8221;</a> mechanism instead of
callbacks: it gives faster and cleaner code. It also avoids a
SELinux issue whereby the setting of <tt class="docutils literal">deny_execmem</tt> must be left
to <tt class="docutils literal">off</tt> in order to use callbacks. (A fix in cffi was
attempted&#8212;see the <tt class="docutils literal">ffi_closure_alloc</tt> branch&#8212;but was not
merged because it creates potential memory corruption with
<tt class="docutils literal">fork()</tt>. For more information, <a class="reference external" href="https://bugzilla.redhat.com/show_bug.cgi?id=1249685">see here.</a>)
</div>
Warning: like ffi.new(), ffi.callback() returns a cdata that has
ownership of its C data. (In this case, the necessary C data contains
the libffi data structures to do a callback.) This means that the
callback can only be invoked as long as this cdata object is alive.
If you store the function pointer into C code, then make sure you also
keep this object alive for as long as the callback may be invoked.
The easiest way to do that is to always use <tt class="docutils literal">&#64;ffi.callback()</tt> at
module-level only, and to pass &#8220;context&#8221; information around with
<a class="reference external" href="ref.html#new-handle">ffi.new_handle()</a>, if possible. Example:
<div class="highlight-python"><div class="highlight"><pre># a good way to use this decorator is once at global level
@ffi.callback(&quot;int(int, void *)&quot;)
def my_global_callback(x, handle):
 return ffi.from_handle(handle).some_method(x)

class Foo(object):

def __init__(self):
 handle = ffi.new_handle(self)
 self._handle = handle # must be kept alive
 lib.register_stuff_with_callback_and_voidp_arg(my_global_callback, handle)

def some_method(self, x):
 print &quot;method called!&quot;
</pre></div>
</div>
(See also the section about <a class="reference internal" href="#id3">extern &#8220;Python&#8221;</a> above, where the same
general style is used.)
Note that callbacks of a variadic function type are not supported. A
workaround is to add custom C code. In the following example, a
callback gets a first argument that counts how many extra <tt class="docutils literal">int</tt>
arguments are passed:
<div class="highlight-python"><div class="highlight"><pre># file &quot;example_build.py&quot;

import cffi

ffibuilder = cffi.FFI()
ffibuilder.cdef(&quot;&quot;&quot;
 int (*python_callback)(int how_many, int *values);
 void *const c_callback; /* pass this const ptr to C routines */
&quot;&quot;&quot;)
ffibuilder.set_source(&quot;_example&quot;, r&quot;&quot;&quot;
 #include &lt;stdarg.h&gt;
 #include &lt;alloca.h&gt;
 static int (*python_callback)(int how_many, int *values);
 static int c_callback(int how_many, ...) {
 va_list ap;
 /* collect the &quot;...&quot; arguments into the values[] array */
 int i, *values = alloca(how_many * sizeof(int));
 va_start(ap, how_many);
 for (i=0; i&lt;how_many; i++)
 values[i] = va_arg(ap, int);
 va_end(ap);
 return python_callback(how_many, values);
 }
&quot;&quot;&quot;)
ffibuilder.compile(verbose=True)
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre># file &quot;example.py&quot;

from _example import ffi, lib

@ffi.callback(&quot;int(int, int *)&quot;)
def python_callback(how_many, values):
 print ffi.unpack(values, how_many)
 return 0
lib.python_callback = python_callback
</pre></div>
</div>
Deprecated: you can also use <tt class="docutils literal">ffi.callback()</tt> not as a decorator but
directly as <tt class="docutils literal">ffi.callback(&quot;int(int, int)&quot;, myfunc)</tt>. This is
discouraged: using this a style, we are more likely to forget the
callback object too early, when it is still in use.
The <tt class="docutils literal">ffi.callback()</tt> decorator also accepts the optional argument
<tt class="docutils literal">error</tt>, and from CFFI version 1.2 the optional argument <tt class="docutils literal">onerror</tt>.
These two work in the same way as <a class="reference internal" href="#error-onerror">described above for extern &#8220;Python&#8221;.</a>
</div>
<div class="section" id="windows-calling-conventions">
<h2><a class="toc-backref" href="#id24">Windows: calling conventions</a><a class="headerlink" href="#windows-calling-conventions" title="Permalink to this headline">¶</a></h2>
On Win32, functions can have two main calling conventions: either
&#8220;cdecl&#8221; (the default), or &#8220;stdcall&#8221; (also known as &#8220;WINAPI&#8221;). There
are also other rare calling conventions, but these are not supported.
New in version 1.3.
When you issue calls from Python to C, the implementation is such that
it works with any of these two main calling conventions; you don&#8217;t
have to specify it. However, if you manipulate variables of type
&#8220;function pointer&#8221; or declare callbacks, then the calling convention
must be correct. This is done by writing <tt class="docutils literal">__cdecl</tt> or <tt class="docutils literal">__stdcall</tt>
in the type, like in C:
<div class="highlight-python"><div class="highlight"><pre>@ffi.callback(&quot;int __stdcall(int, int)&quot;)
def AddNumbers(x, y):
 return x + y
</pre></div>
</div>
or:
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.cdef(&quot;&quot;&quot;
 struct foo_s {
 int (__stdcall *MyFuncPtr)(int, int);
 };
&quot;&quot;&quot;)
</pre></div>
</div>
<tt class="docutils literal">__cdecl</tt> is supported but is always the default so it can be left
out. In the <tt class="docutils literal">cdef()</tt>, you can also use <tt class="docutils literal">WINAPI</tt> as equivalent to
<tt class="docutils literal">__stdcall</tt>. As mentioned above, it is mostly not needed (but doesn&#8217;t
hurt) to say <tt class="docutils literal">WINAPI</tt> or <tt class="docutils literal">__stdcall</tt> when declaring a plain
function in the <tt class="docutils literal">cdef()</tt>. (The difference can still be seen if you
take explicitly a pointer to this function with <tt class="docutils literal">ffi.addressof()</tt>,
or if the function is <tt class="docutils literal">extern &quot;Python&quot;</tt>.)
These calling convention specifiers are accepted but ignored on any
platform other than 32-bit Windows.
In CFFI versions before 1.3, the calling convention specifiers are not
recognized. In API mode, you could work around it by using an
indirection, like in the example in the section about <a class="reference internal" href="#callbacks">Callbacks</a>
(<tt class="docutils literal">&quot;example_build.py&quot;</tt>). There was no way to use stdcall callbacks
in ABI mode.
</div>
<div class="section" id="ffi-interface">
<h2><a class="toc-backref" href="#id25">FFI Interface</a><a class="headerlink" href="#ffi-interface" title="Permalink to this headline">¶</a></h2>
(The reference for the FFI interface has been moved to the <a class="reference external" href="ref.html">next page</a>.)
</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="#">Using the ffi/lib objects</a><ul>
<li><a class="reference internal" href="#working-with-pointers-structures-and-arrays">Working with pointers, structures and arrays</a></li>
<li><a class="reference internal" href="#python-3-support">Python 3 support</a></li>
<li><a class="reference internal" href="#an-example-of-calling-a-main-like-thing">An example of calling a main-like thing</a></li>
<li><a class="reference internal" href="#function-calls">Function calls</a></li>
<li><a class="reference internal" href="#variadic-function-calls">Variadic function calls</a></li>
<li><a class="reference internal" href="#extern-python-new-style-callbacks">Extern &#8220;Python&#8221; (new-style callbacks)</a><ul>
<li><a class="reference internal" href="#extern-python-and-void-arguments">Extern &#8220;Python&#8221; and <tt class="docutils literal">void *</tt> arguments</a></li>
<li><a class="reference internal" href="#extern-python-accessed-from-c-directly">Extern &#8220;Python&#8221; accessed from C directly</a></li>
<li><a class="reference internal" href="#extern-python-c">Extern &#8220;Python+C&#8221;</a></li>
<li><a class="reference internal" href="#extern-python-reference">Extern &#8220;Python&#8221;: reference</a></li>
</ul>
</li>
<li><a class="reference internal" href="#callbacks-old-style">Callbacks (old style)</a></li>
<li><a class="reference internal" href="#windows-calling-conventions">Windows: calling conventions</a></li>
<li><a class="reference internal" href="#ffi-interface">FFI Interface</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="overview.html"
 title="previous chapter">Overview</a>
 <h4>Next topic</h4>
 <a href="ref.html"
 title="next chapter">CFFI Reference</a>
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/using.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="ref.html" title="CFFI Reference"
 >next</a> |</li>
 <li class="right" >
 <a href="overview.html" title="Overview"
 >previous</a> |</li>
 <li><a href="index.html">CFFI 1.9.1 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>