EVOLUTION-MANAGER

Edit File: ref.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>CFFI Reference &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="Preparing and Distributing modules" href="cdef.html" />
 <link rel="prev" title="Using the ffi/lib objects" href="using.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="cdef.html" title="Preparing and Distributing modules"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="using.html" title="Using the ffi/lib objects"
 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="cffi-reference">
<h1><a class="toc-backref" href="#id3">CFFI Reference</a><a class="headerlink" href="#cffi-reference" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
Contents
<ul class="simple">
<li><a class="reference internal" href="#cffi-reference" id="id3">CFFI Reference</a><ul>
<li><a class="reference internal" href="#ffi-interface" id="id4">FFI Interface</a><ul>
<li><a class="reference internal" href="#ffi-null" id="id5">ffi.NULL</a></li>
<li><a class="reference internal" href="#ffi-error" id="id6">ffi.error</a></li>
<li><a class="reference internal" href="#ffi-new" id="id7">ffi.new()</a></li>
<li><a class="reference internal" href="#ffi-cast" id="id8">ffi.cast()</a></li>
<li><a class="reference internal" href="#ffi-errno-ffi-getwinerror" id="id9">ffi.errno, ffi.getwinerror()</a></li>
<li><a class="reference internal" href="#ffi-string-ffi-unpack" id="id10">ffi.string(), ffi.unpack()</a></li>
<li><a class="reference internal" href="#ffi-buffer-ffi-from-buffer" id="id11">ffi.buffer(), ffi.from_buffer()</a></li>
<li><a class="reference internal" href="#ffi-memmove" id="id12">ffi.memmove()</a></li>
<li><a class="reference internal" href="#ffi-typeof-ffi-sizeof-ffi-alignof" id="id13">ffi.typeof(), ffi.sizeof(), ffi.alignof()</a></li>
<li><a class="reference internal" href="#ffi-offsetof-ffi-addressof" id="id14">ffi.offsetof(), ffi.addressof()</a></li>
<li><a class="reference internal" href="#ffi-cdata-ffi-ctype" id="id15">ffi.CData, ffi.CType</a></li>
<li><a class="reference internal" href="#ffi-gc" id="id16">ffi.gc()</a></li>
<li><a class="reference internal" href="#ffi-new-handle-ffi-from-handle" id="id17">ffi.new_handle(), ffi.from_handle()</a></li>
<li><a class="reference internal" href="#ffi-dlopen-ffi-dlclose" id="id18">ffi.dlopen(), ffi.dlclose()</a></li>
<li><a class="reference internal" href="#ffi-new-allocator" id="id19">ffi.new_allocator()</a></li>
<li><a class="reference internal" href="#ffi-init-once" id="id20">ffi.init_once()</a></li>
<li><a class="reference internal" href="#ffi-getctype-ffi-list-types" id="id21">ffi.getctype(), ffi.list_types()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conversions" id="id22">Conversions</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="ffi-interface">
<h2><a class="toc-backref" href="#id4">FFI Interface</a><a class="headerlink" href="#ffi-interface" title="Permalink to this headline">¶</a></h2>
<div class="section" id="ffi-null">
<h3><a class="toc-backref" href="#id5">ffi.NULL</a><a class="headerlink" href="#ffi-null" title="Permalink to this headline">¶</a></h3>
ffi.NULL: a constant NULL of type <tt class="docutils literal">&lt;cdata 'void *'&gt;</tt>.
</div>
<div class="section" id="ffi-error">
<h3><a class="toc-backref" href="#id6">ffi.error</a><a class="headerlink" href="#ffi-error" title="Permalink to this headline">¶</a></h3>
ffi.error: the Python exception raised in various cases. (Don&#8217;t
confuse it with <tt class="docutils literal">ffi.errno</tt>.)
</div>
<div class="section" id="ffi-new">
<h3><a class="toc-backref" href="#id7">ffi.new()</a><a class="headerlink" href="#ffi-new" title="Permalink to this headline">¶</a></h3>
ffi.new(cdecl, init=None):
allocate an instance according to the specified C type and return a
pointer to it. The specified C type must be either a pointer or an
array: <tt class="docutils literal">new('X *')</tt> allocates an X and returns a pointer to it,
whereas <tt class="docutils literal">new('X[n]')</tt> allocates an array of n X&#8217;es and returns an
array referencing it (which works mostly like a pointer, like in C).
You can also use <tt class="docutils literal">new('X[]', n)</tt> to allocate an array of a
non-constant length n. See the <a class="reference external" href="using.html#working">detailed documentation</a> for other
valid initializers.
When the returned <tt class="docutils literal">&lt;cdata&gt;</tt> object goes out of scope, the memory is
freed. In other words the returned <tt class="docutils literal">&lt;cdata&gt;</tt> object has ownership of
the value of type <tt class="docutils literal">cdecl</tt> that it points to. This means that the raw
data can be used as long as this object is kept alive, but must not be
used for a longer time. Be careful about that when copying the
pointer to the memory somewhere else, e.g. into another structure.
</div>
<div class="section" id="ffi-cast">
<h3><a class="toc-backref" href="#id8">ffi.cast()</a><a class="headerlink" href="#ffi-cast" title="Permalink to this headline">¶</a></h3>
ffi.cast(&#8220;C type&#8221;, value): similar to a C cast: returns an
instance of the named C type initialized with the given value. The
value is casted between integers or pointers of any type.
</div>
<div class="section" id="ffi-errno-ffi-getwinerror">
<h3><a class="toc-backref" href="#id9">ffi.errno, ffi.getwinerror()</a><a class="headerlink" href="#ffi-errno-ffi-getwinerror" title="Permalink to this headline">¶</a></h3>
ffi.errno: the value of <tt class="docutils literal">errno</tt> received from the most recent C call
in this thread, and passed to the following C call. (This is a read-write
property.)
ffi.getwinerror(code=-1): on Windows, in addition to <tt class="docutils literal">errno</tt> we
also save and restore the <tt class="docutils literal">GetLastError()</tt> value across function
calls. This function returns this error code as a tuple <tt class="docutils literal">(code,
message)</tt>, adding a readable message like Python does when raising
WindowsError. If the argument <tt class="docutils literal">code</tt> is given, format that code into
a message instead of using <tt class="docutils literal">GetLastError()</tt>.
(Note that it is also possible to declare and call the <tt class="docutils literal">GetLastError()</tt>
function as usual.)
</div>
<div class="section" id="ffi-string-ffi-unpack">
<h3><a class="toc-backref" href="#id10">ffi.string(), ffi.unpack()</a><a class="headerlink" href="#ffi-string-ffi-unpack" title="Permalink to this headline">¶</a></h3>
ffi.string(cdata, [maxlen]): return a Python string (or unicode
string) from the &#8216;cdata&#8217;.
<ul class="simple">
<li>If &#8216;cdata&#8217; is a pointer or array of characters or bytes, returns the
null-terminated string. The returned string extends until the first
null character. The &#8216;maxlen&#8217; argument limits how far we look for a
null character. If &#8216;cdata&#8217; is an
array then &#8216;maxlen&#8217; defaults to its length. See <tt class="docutils literal">ffi.unpack()</tt> below
for a way to continue past the first null character. Python 3: this
returns a <tt class="docutils literal">bytes</tt>, not a <tt class="docutils literal">str</tt>.</li>
<li>If &#8216;cdata&#8217; is a pointer or array of wchar_t, returns a unicode string
following the same rules.</li>
<li>If &#8216;cdata&#8217; is a single character or byte or a wchar_t, returns it as a
byte string or unicode string. (Note that in some situation a single
wchar_t may require a Python unicode string of length 2.)</li>
<li>If &#8216;cdata&#8217; is an enum, returns the value of the enumerator as a string.
If the value is out of range, it is simply returned as the stringified
integer.</li>
</ul>
ffi.unpack(cdata, length): unpacks an array of C data of the given
length, returning a Python string/unicode/list. The &#8216;cdata&#8217; should be
a pointer; if it is an array it is first converted to the pointer
type. New in version 1.6.
<ul class="simple">
<li>If &#8216;cdata&#8217; is a pointer to &#8216;char&#8217;, returns a byte string. It does
not stop at the first null. (An equivalent way to do that is
<tt class="docutils literal">ffi.buffer(cdata, length)[:]</tt>.)</li>
<li>If &#8216;cdata&#8217; is a pointer to &#8216;wchar_t&#8217;, returns a unicode string.
(&#8216;length&#8217; is measured in number of wchar_t; it is not the size in
bytes.)</li>
<li>If &#8216;cdata&#8217; is a pointer to anything else, returns a list, of the
given &#8216;length&#8217;. (A slower way to do that is <tt class="docutils literal">[cdata[i] for i in
range(length)]</tt>.)</li>
</ul>
</div>
<div class="section" id="ffi-buffer-ffi-from-buffer">
<h3><a class="toc-backref" href="#id11">ffi.buffer(), ffi.from_buffer()</a><a class="headerlink" href="#ffi-buffer-ffi-from-buffer" title="Permalink to this headline">¶</a></h3>
ffi.buffer(cdata, [size]): return a buffer object that references
the raw C data pointed to by the given &#8216;cdata&#8217;, of &#8216;size&#8217; bytes. The
&#8216;cdata&#8217; must be a pointer or an array. If unspecified, the size of the
buffer is either the size of what <tt class="docutils literal">cdata</tt> points to, or the whole size
of the array. Getting a buffer is useful because you can read from it
without an extra copy, or write into it to change the original value.
Here are a few examples of where buffer() would be useful:
<ul class="simple">
<li>use <tt class="docutils literal">file.write()</tt> and <tt class="docutils literal">file.readinto()</tt> with
such a buffer (for files opened in binary mode)</li>
<li>use <tt class="docutils literal">ffi.buffer(mystruct[0])[:] = socket.recv(len(buffer))</tt> to read
into a struct over a socket, rewriting the contents of mystruct[0]</li>
</ul>
Remember that like in C, you can use <tt class="docutils literal">array + index</tt> to get the pointer
to the index&#8217;th item of an array. (In C you might more naturally write
<tt class="docutils literal">&amp;array[index]</tt>, but that is equivalent.)
The returned object is not a built-in buffer nor memoryview object,
because these objects&#8217; API changes too much across Python versions.
Instead it has the following Python API (a subset of Python 2&#8217;s
<tt class="docutils literal">buffer</tt>):
<ul class="simple">
<li><tt class="docutils literal">buf[:]</tt> or <tt class="docutils literal">bytes(buf)</tt>: fetch a copy as a regular byte string (or
<tt class="docutils literal">buf[start:end]</tt> for a part)</li>
<li><tt class="docutils literal">buf[:] = newstr</tt>: change the original content (or <tt class="docutils literal">buf[start:end]
= newstr</tt>)</li>
<li><tt class="docutils literal">len(buf), buf[index], buf[index] = newchar</tt>: access as a sequence
of characters.</li>
</ul>
The buffer object returned by <tt class="docutils literal">ffi.buffer(cdata)</tt> keeps alive the
<tt class="docutils literal">cdata</tt> object: if it was originally an owning cdata, then its
owned memory will not be freed as long as the buffer is alive.
Python 2/3 compatibility note: you should avoid using <tt class="docutils literal">str(buf)</tt>,
because it gives inconsistent results between Python 2 and Python 3.
(This is similar to how <tt class="docutils literal">str()</tt> gives inconsistent results on regular
byte strings). Use <tt class="docutils literal">buf[:]</tt> instead.
ffi.from_buffer(python_buffer): return a <tt class="docutils literal">&lt;cdata 'char[]'&gt;</tt> that
points to the data of the given Python object, which must support the
buffer interface. This is the opposite of <tt class="docutils literal">ffi.buffer()</tt>. It gives
a reference to the existing data, not a copy; for this
reason, and for PyPy compatibility, it does not work with the built-in
type unicode; nor buffers/memoryviews to byte or unicode strings.
It is meant to be used on objects
containing large quantities of raw data, like bytearrays
or <tt class="docutils literal">array.array</tt> or numpy
arrays. It supports both the old buffer API (in Python 2.x) and the
new memoryview API. Note that if you pass a read-only buffer object,
you still get a regular <tt class="docutils literal">&lt;cdata 'char[]'&gt;</tt>; it is your responsibility
not to write there if the original buffer doesn&#8217;t expect you to.
The original object is kept alive (and, in case
of memoryview, locked) as long as the cdata object returned by
<tt class="docutils literal">ffi.from_buffer()</tt> is alive.
A common use case is calling a C function with some <tt class="docutils literal">char *</tt> that
points to the internal buffer of a Python object; for this case you
can directly pass <tt class="docutils literal">ffi.from_buffer(python_buffer)</tt> as argument to
the call.
New in version 1.7: the python_buffer can be a bytearray object.
Be careful: if the bytearray gets resized (e.g. its <tt class="docutils literal">.append()</tt>
method is called), then the <tt class="docutils literal">&lt;cdata&gt;</tt> object will point to freed
memory and must not be used any more.
New in version 1.8: the python_buffer can be a byte string (but still
not a buffer/memoryview on a string).
</div>
<div class="section" id="ffi-memmove">
<h3><a class="toc-backref" href="#id12">ffi.memmove()</a><a class="headerlink" href="#ffi-memmove" title="Permalink to this headline">¶</a></h3>
ffi.memmove(dest, src, n): copy <tt class="docutils literal">n</tt> bytes from memory area
<tt class="docutils literal">src</tt> to memory area <tt class="docutils literal">dest</tt>. See examples below. Inspired by the
C functions <tt class="docutils literal">memcpy()</tt> and <tt class="docutils literal">memmove()</tt>&#8212;like the latter, the
areas can overlap. Each of <tt class="docutils literal">dest</tt> and <tt class="docutils literal">src</tt> can be either a cdata
pointer or a Python object supporting the buffer/memoryview interface.
In the case of <tt class="docutils literal">dest</tt>, the buffer/memoryview must be writable.
Unlike <tt class="docutils literal">ffi.from_buffer()</tt>, there are no restrictions on the type of
buffer. New in version 1.3. Examples:
<ul class="simple">
<li><tt class="docutils literal">ffi.memmove(myptr, b&quot;hello&quot;, 5)</tt> copies the 5 bytes of
<tt class="docutils literal">b&quot;hello&quot;</tt> to the area that <tt class="docutils literal">myptr</tt> points to.</li>
<li><tt class="docutils literal">ba = bytearray(100); ffi.memmove(ba, myptr, 100)</tt> copies 100
bytes from <tt class="docutils literal">myptr</tt> into the bytearray <tt class="docutils literal">ba</tt>.</li>
<li><tt class="docutils literal">ffi.memmove(myptr + 1, myptr, 100)</tt> shifts 100 bytes from
the memory at <tt class="docutils literal">myptr</tt> to the memory at <tt class="docutils literal">myptr + 1</tt>.</li>
</ul>
</div>
<div class="section" id="ffi-typeof-ffi-sizeof-ffi-alignof">
<h3><a class="toc-backref" href="#id13">ffi.typeof(), ffi.sizeof(), ffi.alignof()</a><a class="headerlink" href="#ffi-typeof-ffi-sizeof-ffi-alignof" title="Permalink to this headline">¶</a></h3>
ffi.typeof(&#8220;C type&#8221; or cdata object): return an object of type
<tt class="docutils literal">&lt;ctype&gt;</tt> corresponding to the parsed string, or to the C type of the
cdata instance. Usually you don&#8217;t need to call this function or to
explicitly manipulate <tt class="docutils literal">&lt;ctype&gt;</tt> objects in your code: any place that
accepts a C type can receive either a string or a pre-parsed <tt class="docutils literal">ctype</tt>
object (and because of caching of the string, there is no real
performance difference). It can still be useful in writing typechecks,
e.g.:
<div class="highlight-python"><div class="highlight"><pre>def myfunction(ptr):
 assert ffi.typeof(ptr) is ffi.typeof(&quot;foo_t*&quot;)
 ...
</pre></div>
</div>
Note also that the mapping from strings like <tt class="docutils literal">&quot;foo_t*&quot;</tt> to the
<tt class="docutils literal">&lt;ctype&gt;</tt> objects is stored in some internal dictionary. This
guarantees that there is only one <tt class="docutils literal">&lt;ctype 'foo_t *'&gt;</tt> object, so you
can use the <tt class="docutils literal">is</tt> operator to compare it. The downside is that the
dictionary entries are immortal for now. In the future, we may add
transparent reclamation of old, unused entries. In the meantime, note
that using strings like <tt class="docutils literal">&quot;int[%d]&quot; % length</tt> to name a type will
create many immortal cached entries if called with many different
lengths.
ffi.sizeof(&#8220;C type&#8221; or cdata object): return the size of the
argument in bytes. The argument can be either a C type, or a cdata object,
like in the equivalent <tt class="docutils literal">sizeof</tt> operator in C.
For <tt class="docutils literal">array = ffi.new(&quot;T[]&quot;, n)</tt>, then <tt class="docutils literal">ffi.sizeof(array)</tt> returns
<tt class="docutils literal">n * ffi.sizeof(&quot;T&quot;)</tt>. New in version 1.9: Similar rules apply for
structures with aa variable-sized array at the end. More precisely, if
<tt class="docutils literal">p</tt> was returned by <tt class="docutils literal">ffi.new(&quot;struct foo *&quot;, ...)</tt>, then
<tt class="docutils literal">ffi.sizeof(p[0])</tt> now returns the total allocated size. In previous
versions, it used to just return <tt class="docutils literal">ffi.sizeof(ffi.typeof(p[0]))</tt>, which
is the size of the structure ignoring the variable-sized part. (Note
that due to alignment, it is possible for <tt class="docutils literal">ffi.sizeof(p[0])</tt> to return
a value smaller than <tt class="docutils literal">ffi.sizeof(ffi.typeof(p[0]))</tt>.)
ffi.alignof(&#8220;C type&#8221;): return the natural alignment size in bytes of
the argument. Corresponds to the <tt class="docutils literal">__alignof__</tt> operator in GCC.
</div>
<div class="section" id="ffi-offsetof-ffi-addressof">
<h3><a class="toc-backref" href="#id14">ffi.offsetof(), ffi.addressof()</a><a class="headerlink" href="#ffi-offsetof-ffi-addressof" title="Permalink to this headline">¶</a></h3>
ffi.offsetof(&#8220;C struct or array type&#8221;, *fields_or_indexes): return the
offset within the struct of the given field. Corresponds to <tt class="docutils literal">offsetof()</tt>
in C.
You can give several field names in case of nested structures. You
can also give numeric values which correspond to array items, in case
of a pointer or array type. For example, <tt class="docutils literal">ffi.offsetof(&quot;int[5]&quot;, 2)</tt>
is equal to the size of two integers, as is <tt class="docutils literal">ffi.offsetof(&quot;int *&quot;, 2)</tt>.
ffi.addressof(cdata, *fields_or_indexes): limited equivalent to
the &#8216;&amp;&#8217; operator in C:
1. <tt class="docutils literal">ffi.addressof(&lt;cdata 'struct-or-union'&gt;)</tt> returns a cdata that
is a pointer to this struct or union. The returned pointer is only
valid as long as the original <tt class="docutils literal">cdata</tt> object is; be sure to keep it
alive if it was obtained directly from <tt class="docutils literal">ffi.new()</tt>.
2. <tt class="docutils literal">ffi.addressof(&lt;cdata&gt;, field-or-index...)</tt> returns the address
of a field or array item inside the given structure or array. In case
of nested structures or arrays, you can give more than one field or
index to look recursively. Note that <tt class="docutils literal">ffi.addressof(array, index)</tt>
can also be expressed as <tt class="docutils literal">array + index</tt>: this is true both in CFFI
and in C, where <tt class="docutils literal">&amp;array[index]</tt> is just <tt class="docutils literal">array + index</tt>.
3. <tt class="docutils literal">ffi.addressof(&lt;library&gt;, &quot;name&quot;)</tt> returns the address of the
named function or global variable from the given library object.
For functions, it returns a regular cdata
object containing a pointer to the function.
Note that the case 1. cannot be used to take the address of a
primitive or pointer, but only a struct or union. It would be
difficult to implement because only structs and unions are internally
stored as an indirect pointer to the data. If you need a C int whose
address can be taken, use <tt class="docutils literal">ffi.new(&quot;int[1]&quot;)</tt> in the first place;
similarly, for a pointer, use <tt class="docutils literal">ffi.new(&quot;foo_t *[1]&quot;)</tt>.
</div>
<div class="section" id="ffi-cdata-ffi-ctype">
<h3><a class="toc-backref" href="#id15">ffi.CData, ffi.CType</a><a class="headerlink" href="#ffi-cdata-ffi-ctype" title="Permalink to this headline">¶</a></h3>
ffi.CData, ffi.CType: the Python type of the objects referred to
as <tt class="docutils literal">&lt;cdata&gt;</tt> and <tt class="docutils literal">&lt;ctype&gt;</tt> in the rest of this document. Note
that some cdata objects may be actually of a subclass of
<tt class="docutils literal">ffi.CData</tt>, and similarly with ctype, so you should check with
<tt class="docutils literal">if isinstance(x, ffi.CData)</tt>. Also, <tt class="docutils literal">&lt;ctype&gt;</tt> objects have
a number of attributes for introspection: <tt class="docutils literal">kind</tt> and <tt class="docutils literal">cname</tt> are
always present, and depending on the kind they may also have
<tt class="docutils literal">item</tt>, <tt class="docutils literal">length</tt>, <tt class="docutils literal">fields</tt>, <tt class="docutils literal">args</tt>, <tt class="docutils literal">result</tt>, <tt class="docutils literal">ellipsis</tt>,
<tt class="docutils literal">abi</tt>, <tt class="docutils literal">elements</tt> and <tt class="docutils literal">relements</tt>.
</div>
<div class="section" id="ffi-gc">
<h3><a class="toc-backref" href="#id16">ffi.gc()</a><a class="headerlink" href="#ffi-gc" title="Permalink to this headline">¶</a></h3>
ffi.gc(cdata, destructor): return a new cdata object that points to the
same data. Later, when this new cdata object is garbage-collected,
<tt class="docutils literal">destructor(old_cdata_object)</tt> will be called. Example of usage:
<tt class="docutils literal">ptr = ffi.gc(lib.malloc(42), lib.free)</tt>. Note that like objects
returned by <tt class="docutils literal">ffi.new()</tt>, the returned pointer objects have ownership,
which means the destructor is called as soon as this exact returned
object is garbage-collected.
ffi.gc(ptr, None): removes the ownership on a object returned by a
regular call to <tt class="docutils literal">ffi.gc</tt>, and no destructor will be called when it
is garbage-collected. The object is modified in-place, and the
function returns <tt class="docutils literal">None</tt>. New in version 1.7: ffi.gc(ptr, None)
Note that <tt class="docutils literal">ffi.gc()</tt> should be avoided for large memory allocations or
for limited resources. This is particularly true on PyPy: its GC does
not know how much memory or how many resources the returned <tt class="docutils literal">ptr</tt>
holds. It will only run its GC when enough memory it knows about has
been allocated (and thus run the destructor possibly later than you
would expect). Moreover, the destructor is called in whatever thread
PyPy is at that moment, which might be a problem for some C libraries.
In these cases, consider writing a wrapper class with custom <tt class="docutils literal">__enter__()</tt>
and <tt class="docutils literal">__exit__()</tt> methods, allocating and freeing the C data at known
points in time, and using it in a <tt class="docutils literal">with</tt> statement.
</div>
<div class="section" id="ffi-new-handle-ffi-from-handle">
<h3><a class="toc-backref" href="#id17">ffi.new_handle(), ffi.from_handle()</a><a class="headerlink" href="#ffi-new-handle-ffi-from-handle" title="Permalink to this headline">¶</a></h3>
ffi.new_handle(python_object): return a non-NULL cdata of type
<tt class="docutils literal">void *</tt> that contains an opaque reference to <tt class="docutils literal">python_object</tt>. You
can pass it around to C functions or store it into C structures. Later,
you can use ffi.from_handle(p) to retrieve the original
<tt class="docutils literal">python_object</tt> from a value with the same <tt class="docutils literal">void *</tt> pointer.
Calling ffi.from_handle(p) is invalid and will likely crash if
the cdata object returned by new_handle() is not kept alive!
See a <a class="reference internal" href="#typical-usage-example">typical usage example</a> below.
(In case you are wondering, this <tt class="docutils literal">void *</tt> is not the <tt class="docutils literal">PyObject *</tt>
pointer. This wouldn&#8217;t make sense on PyPy anyway.)
The <tt class="docutils literal">ffi.new_handle()/from_handle()</tt> functions conceptually work
like this:
<ul class="simple">
<li><tt class="docutils literal">new_handle()</tt> returns cdata objects that contains references to
the Python objects; we call them collectively the &#8220;handle&#8221; cdata
objects. The <tt class="docutils literal">void *</tt> value in these handle cdata objects are
random but unique.</li>
<li><tt class="docutils literal">from_handle(p)</tt> searches all live &#8220;handle&#8221; cdata objects for the
one that has the same value <tt class="docutils literal">p</tt> as its <tt class="docutils literal">void *</tt> value. It then
returns the Python object referenced by that handle cdata object.
If none is found, you get &#8220;undefined behavior&#8221; (i.e. crashes).</li>
</ul>
The &#8220;handle&#8221; cdata object keeps the Python object alive, similar to
how <tt class="docutils literal">ffi.new()</tt> returns a cdata object that keeps a piece of memory
alive. If the handle cdata object itself is not alive any more,
then the association <tt class="docutils literal">void * -&gt; python_object</tt> is dead and
<tt class="docutils literal">from_handle()</tt> will crash.
New in version 1.4: two calls to <tt class="docutils literal">new_handle(x)</tt> are guaranteed to
return cdata objects with different <tt class="docutils literal">void *</tt> values, even with the
same <tt class="docutils literal">x</tt>. This is a useful feature that avoids issues with unexpected
duplicates in the following trick: if you need to keep alive the
&#8220;handle&#8221; until explicitly asked to free it, but don&#8217;t have a natural
Python-side place to attach it to, then the easiest is to <tt class="docutils literal">add()</tt> it
to a global set. It can later be removed from the set by
<tt class="docutils literal">global_set.discard(p)</tt>, with <tt class="docutils literal">p</tt> any cdata object whose <tt class="docutils literal">void *</tt>
value compares equal.
Usage example: suppose you have a C library where you must call a
<tt class="docutils literal">lib.process_document()</tt> function which invokes some callback. The
<tt class="docutils literal">process_document()</tt> function receives a pointer to a callback and a
<tt class="docutils literal">void *</tt> argument. The callback is then invoked with the <tt class="docutils literal">void
*data</tt> argument that is equal to the provided value. In this typical
case, you can implement it like this (out-of-line API mode):
<div class="highlight-python"><div class="highlight"><pre>class MyDocument:
 ...

def process(self):
 h = ffi.new_handle(self)
 lib.process_document(lib.my_callback, # the callback
 h, # &#39;void *data&#39;
 args...)
 # &#39;h&#39; stays alive until here, which means that the
 # ffi.from_handle() done in my_callback() during
 # the call to process_document() is safe

def callback(self, arg1, arg2):
 ...

# the actual callback is this one-liner global function:
@ffi.def_extern
def my_callback(arg1, arg2, data):
 return ffi.from_handle(data).callback(arg1, arg2)
</pre></div>
</div>
</div>
<div class="section" id="ffi-dlopen-ffi-dlclose">
<h3><a class="toc-backref" href="#id18">ffi.dlopen(), ffi.dlclose()</a><a class="headerlink" href="#ffi-dlopen-ffi-dlclose" title="Permalink to this headline">¶</a></h3>
ffi.dlopen(libpath, [flags]): opens and returns a &#8220;handle&#8221; to a
dynamic library, as a <tt class="docutils literal">&lt;lib&gt;</tt> object. See <a class="reference external" href="cdef.html#loading-libraries">Preparing and
Distributing modules</a>.
ffi.dlclose(lib): explicitly closes a <tt class="docutils literal">&lt;lib&gt;</tt> object returned
by <tt class="docutils literal">ffi.dlopen()</tt>.
ffi.RLTD_...: constants: flags for <tt class="docutils literal">ffi.dlopen()</tt>.
</div>
<div class="section" id="ffi-new-allocator">
<h3><a class="toc-backref" href="#id19">ffi.new_allocator()</a><a class="headerlink" href="#ffi-new-allocator" title="Permalink to this headline">¶</a></h3>
ffi.new_allocator(alloc=None, free=None, should_clear_after_alloc=True):
returns a new allocator. An &#8220;allocator&#8221; is a callable that behaves like
<tt class="docutils literal">ffi.new()</tt> but uses the provided low-level <tt class="docutils literal">alloc</tt> and <tt class="docutils literal">free</tt>
functions. New in version 1.2.
<tt class="docutils literal">alloc()</tt> is invoked with the size as sole argument. If it returns
NULL, a MemoryError is raised. Later, if <tt class="docutils literal">free</tt> is not None, it will
be called with the result of <tt class="docutils literal">alloc()</tt> as argument. Both can be either
Python function or directly C functions. If only <tt class="docutils literal">free</tt> is None, then no
free function is called. If both <tt class="docutils literal">alloc</tt> and <tt class="docutils literal">free</tt> are None, the
default alloc/free combination is used. (In other words, the call
<tt class="docutils literal">ffi.new(*args)</tt> is equivalent to <tt class="docutils literal">ffi.new_allocator()(*args)</tt>.)
If <tt class="docutils literal">should_clear_after_alloc</tt> is set to False, then the memory
returned by <tt class="docutils literal">alloc()</tt> is assumed to be already cleared (or you are
fine with garbage); otherwise CFFI will clear it.
</div>
<div class="section" id="ffi-init-once">
<h3><a class="toc-backref" href="#id20">ffi.init_once()</a><a class="headerlink" href="#ffi-init-once" title="Permalink to this headline">¶</a></h3>
ffi.init_once(function, tag): run <tt class="docutils literal">function()</tt> once. The
<tt class="docutils literal">tag</tt> should be a primitive object, like a string, that identifies
the function: <tt class="docutils literal">function()</tt> is only called the first time we see the
<tt class="docutils literal">tag</tt>. The return value of <tt class="docutils literal">function()</tt> is remembered and
returned by the current and all future <tt class="docutils literal">init_once()</tt> with the same
tag. If <tt class="docutils literal">init_once()</tt> is called from multiple threads in parallel,
all calls block until the execution of <tt class="docutils literal">function()</tt> is done. If
<tt class="docutils literal">function()</tt> raises an exception, it is propagated and nothing is
cached (i.e. <tt class="docutils literal">function()</tt> will be called again, in case we catch the
exception and try <tt class="docutils literal">init_once()</tt> again). New in version 1.4.
Example:
<div class="highlight-python"><div class="highlight"><pre>from _xyz_cffi import ffi, lib

def initlib():
 lib.init_my_library()

def make_new_foo():
 ffi.init_once(initlib, &quot;init&quot;)
 return lib.make_foo()
</pre></div>
</div>
<tt class="docutils literal">init_once()</tt> is optimized to run very quickly if <tt class="docutils literal">function()</tt> has
already been called. (On PyPy, the cost is zero&#8212;the JIT usually
removes everything in the machine code it produces.)
Note: one <a class="reference external" href="https://bitbucket.org/cffi/cffi/issues/233/">motivation</a> for <tt class="docutils literal">init_once()</tt> is the CPython notion of
&#8220;subinterpreters&#8221; in the embedded case. If you are using the
out-of-line API mode, <tt class="docutils literal">function()</tt> is called only once even in the
presence of multiple subinterpreters, and its return value is shared
among all subinterpreters. The goal is to mimic the way traditional
CPython C extension modules have their init code executed only once in
total even if there are subinterpreters. In the example above, the C
function <tt class="docutils literal">init_my_library()</tt> is called once in total, not once per
subinterpreter. For this reason, avoid Python-level side-effects in
<tt class="docutils literal">function()</tt> (as they will only be applied in the first
subinterpreter to run); instead, return a value, as in the following
example:
<div class="highlight-python"><div class="highlight"><pre>def init_get_max():
 return lib.initialize_once_and_get_some_maximum_number()

def process(i):
 if i &gt; ffi.init_once(init_get_max, &quot;max&quot;):
 raise IndexError(&quot;index too large!&quot;)
 ...
</pre></div>
</div>
</div>
<div class="section" id="ffi-getctype-ffi-list-types">
<h3><a class="toc-backref" href="#id21">ffi.getctype(), ffi.list_types()</a><a class="headerlink" href="#ffi-getctype-ffi-list-types" title="Permalink to this headline">¶</a></h3>
ffi.getctype(&#8220;C type&#8221; or &lt;ctype&gt;, extra=&#8221;&#8221;): return the string
representation of the given C type. If non-empty, the &#8220;extra&#8221; string is
appended (or inserted at the right place in more complicated cases); it
can be the name of a variable to declare, or an extra part of the type
like <tt class="docutils literal">&quot;*&quot;</tt> or <tt class="docutils literal">&quot;[5]&quot;</tt>. For example
<tt class="docutils literal">ffi.getctype(ffi.typeof(x), &quot;*&quot;)</tt> returns the string representation
of the C type &#8220;pointer to the same type than x&#8221;; and
<tt class="docutils literal">ffi.getctype(&quot;char[80]&quot;, &quot;a&quot;) == &quot;char a[80]&quot;</tt>.
ffi.list_types(): Returns the user type names known to this FFI
instance. This returns a tuple containing three lists of names:
<tt class="docutils literal">(typedef_names, names_of_structs, names_of_unions)</tt>. New in
version 1.6.
</div>
</div>
<div class="section" id="conversions">
<h2><a class="toc-backref" href="#id22">Conversions</a><a class="headerlink" href="#conversions" title="Permalink to this headline">¶</a></h2>
This section documents all the conversions that are allowed when
writing into a C data structure (or passing arguments to a function
call), and reading from a C data structure (or getting the result of a
function call). The last column gives the type-specific operations
allowed.
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="33%" />
<col width="25%" />
<col width="22%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">C type</th>
<th class="head">writing into</th>
<th class="head">reading from</th>
<th class="head">other operations</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>integers
and enums
<cite>(*****)</cite></td>
<td>an integer or anything
on which int() works
(but not a float!).
Must be within range.</td>
<td>a Python int or
long, depending
on the type</td>
<td>int(), bool()
<cite>(******)</cite></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal">char</tt></td>
<td>a string of length 1
or another &lt;cdata char&gt;</td>
<td>a string of
length 1</td>
<td>int(), bool()</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal">wchar_t</tt></td>
<td>a unicode of length 1
(or maybe 2 if
surrogates) or
another &lt;cdata wchar_t&gt;</td>
<td>a unicode of
length 1
(or maybe 2 if
surrogates)</td>
<td>int(), bool()</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal">float</tt>,
<tt class="docutils literal">double</tt></td>
<td>a float or anything on
which float() works</td>
<td>a Python float</td>
<td>float(), int(),
bool()</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal">long double</tt></td>
<td>another &lt;cdata&gt; with
a <tt class="docutils literal">long double</tt>, or
anything on which
float() works</td>
<td>a &lt;cdata&gt;, to
avoid loosing
precision <cite>(***)</cite></td>
<td>float(), int(),
bool()</td>
</tr>
<tr class="row-odd"><td>pointers</td>
<td>another &lt;cdata&gt; with
a compatible type (i.e.
same type
or <tt class="docutils literal">void*</tt>, or as an
array instead) <cite>(*)</cite></td>
<td rowspan="4">a &lt;cdata&gt;</td>
<td rowspan="2"><tt class="docutils literal">[]</tt> <cite>(****)</cite>,
<tt class="docutils literal">+</tt>, <tt class="docutils literal">-</tt>,
bool()</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal">void *</tt></td>
<td>another &lt;cdata&gt; with
any pointer or array
type</td>
</tr>
<tr class="row-odd"><td>pointers to
structure or
union</td>
<td>same as pointers</td>
<td><tt class="docutils literal">[]</tt>, <tt class="docutils literal">+</tt>,
<tt class="docutils literal">-</tt>, bool(),
and read/write
struct fields</td>
</tr>
<tr class="row-even"><td>function
pointers</td>
<td>same as pointers</td>
<td>bool(),
call <cite>(**)</cite></td>
</tr>
<tr class="row-odd"><td>arrays</td>
<td>a list or tuple of
items</td>
<td rowspan="3">a &lt;cdata&gt;</td>
<td>len(), iter(),
<tt class="docutils literal">[]</tt> <cite>(****)</cite>,
<tt class="docutils literal">+</tt>, <tt class="docutils literal">-</tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal">char[]</tt></td>
<td>same as arrays, or a
Python string</td>
<td>len(), iter(),
<tt class="docutils literal">[]</tt>, <tt class="docutils literal">+</tt>,
<tt class="docutils literal">-</tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal">wchar_t[]</tt></td>
<td>same as arrays, or a
Python unicode</td>
<td>len(), iter(),
<tt class="docutils literal">[]</tt>,
<tt class="docutils literal">+</tt>, <tt class="docutils literal">-</tt></td>
</tr>
<tr class="row-even"><td>structure</td>
<td>a list or tuple or
dict of the field
values, or a same-type
&lt;cdata&gt;</td>
<td rowspan="2">a &lt;cdata&gt;</td>
<td>read/write
fields</td>
</tr>
<tr class="row-odd"><td>union</td>
<td>same as struct, but
with at most one field</td>
<td>read/write
fields</td>
</tr>
</tbody>
</table>
<cite>(*)</cite> <tt class="docutils literal">item *</tt> is <tt class="docutils literal">item[]</tt> in function arguments:
<blockquote>
<div>In a function declaration, as per the C standard, a <tt class="docutils literal">item *</tt>
argument is identical to a <tt class="docutils literal">item[]</tt> argument (and <tt class="docutils literal">ffi.cdef()</tt>
doesn&#8217;t record the difference). So when you call such a function,
you can pass an argument that is accepted by either C type, like
for example passing a Python string to a <tt class="docutils literal">char *</tt> argument
(because it works for <tt class="docutils literal">char[]</tt> arguments) or a list of integers
to a <tt class="docutils literal">int *</tt> argument (it works for <tt class="docutils literal">int[]</tt> arguments). Note
that even if you want to pass a single <tt class="docutils literal">item</tt>, you need to
specify it in a list of length 1; for example, a <tt class="docutils literal">struct point_s
*</tt> argument might be passed as <tt class="docutils literal">[[x, y]]</tt> or <tt class="docutils literal">[{'x': 5, 'y':
10}]</tt>.
As an optimization, CFFI assumes that a
function with a <tt class="docutils literal">char *</tt> argument to which you pass a Python
string will not actually modify the array of characters passed in,
and so passes directly a pointer inside the Python string object.
(On PyPy, this optimization is only available since PyPy 5.4
with CFFI 1.8.)
</div></blockquote>
<cite>(**)</cite> C function calls are done with the GIL released.
<blockquote>
<div>Note that we assume that the called functions are not using the
Python API from Python.h. For example, we don&#8217;t check afterwards
if they set a Python exception. You may work around it, but mixing
CFFI with <tt class="docutils literal">Python.h</tt> is not recommended. (If you do that, on
PyPy and on some platforms like Windows, you may need to explicitly
link to <tt class="docutils literal">libpypy-c.dll</tt> to access the CPython C API compatibility
layer; indeed, CFFI-generated modules on PyPy don&#8217;t link to
<tt class="docutils literal">libpypy-c.dll</tt> on their own. But really, don&#8217;t do that in the
first place.)</div></blockquote>
<cite>(***)</cite> <tt class="docutils literal">long double</tt> support:
<blockquote>
<div>We keep <tt class="docutils literal">long double</tt> values inside a cdata object to avoid
loosing precision. Normal Python floating-point numbers only
contain enough precision for a <tt class="docutils literal">double</tt>. If you really want to
convert such an object to a regular Python float (i.e. a C
<tt class="docutils literal">double</tt>), call <tt class="docutils literal">float()</tt>. If you need to do arithmetic on
such numbers without any precision loss, you need instead to define
and use a family of C functions like <tt class="docutils literal">long double add(long double
a, long double b);</tt>.</div></blockquote>
<cite>(****)</cite> Slicing with <tt class="docutils literal">x[start:stop]</tt>:
<blockquote>
<div>Slicing is allowed, as long as you specify explicitly both <tt class="docutils literal">start</tt>
and <tt class="docutils literal">stop</tt> (and don&#8217;t give any <tt class="docutils literal">step</tt>). It gives a cdata
object that is a &#8220;view&#8221; of all items from <tt class="docutils literal">start</tt> to <tt class="docutils literal">stop</tt>.
It is a cdata of type &#8220;array&#8221; (so e.g. passing it as an argument to a
C function would just convert it to a pointer to the <tt class="docutils literal">start</tt> item).
As with indexing, negative bounds mean really negative indices, like in
C. As for slice assignment, it accepts any iterable, including a list
of items or another array-like cdata object, but the length must match.
(Note that this behavior differs from initialization: e.g. you can
say <tt class="docutils literal">chararray[10:15] = &quot;hello&quot;</tt>, but the assigned string must be of
exactly the correct length; no implicit null character is added.)</div></blockquote>
<cite>(*****)</cite> Enums are handled like ints:
<blockquote>
<div>Like C, enum types are mostly int types (unsigned or signed, int or
long; note that GCC&#8217;s first choice is unsigned). Reading an enum
field of a structure, for example, returns you an integer. To
compare their value symbolically, use code like <tt class="docutils literal">if x.field ==
lib.FOO</tt>. If you really want to get their value as a string, use
<tt class="docutils literal">ffi.string(ffi.cast(&quot;the_enum_type&quot;, x.field))</tt>.</div></blockquote>
<cite>(******)</cite> bool() on a primitive cdata:
<blockquote>
<div>New in version 1.7. In previous versions, it only worked on
pointers; for primitives it always returned True.</div></blockquote>
</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="#">CFFI Reference</a><ul>
<li><a class="reference internal" href="#ffi-interface">FFI Interface</a><ul>
<li><a class="reference internal" href="#ffi-null">ffi.NULL</a></li>
<li><a class="reference internal" href="#ffi-error">ffi.error</a></li>
<li><a class="reference internal" href="#ffi-new">ffi.new()</a></li>
<li><a class="reference internal" href="#ffi-cast">ffi.cast()</a></li>
<li><a class="reference internal" href="#ffi-errno-ffi-getwinerror">ffi.errno, ffi.getwinerror()</a></li>
<li><a class="reference internal" href="#ffi-string-ffi-unpack">ffi.string(), ffi.unpack()</a></li>
<li><a class="reference internal" href="#ffi-buffer-ffi-from-buffer">ffi.buffer(), ffi.from_buffer()</a></li>
<li><a class="reference internal" href="#ffi-memmove">ffi.memmove()</a></li>
<li><a class="reference internal" href="#ffi-typeof-ffi-sizeof-ffi-alignof">ffi.typeof(), ffi.sizeof(), ffi.alignof()</a></li>
<li><a class="reference internal" href="#ffi-offsetof-ffi-addressof">ffi.offsetof(), ffi.addressof()</a></li>
<li><a class="reference internal" href="#ffi-cdata-ffi-ctype">ffi.CData, ffi.CType</a></li>
<li><a class="reference internal" href="#ffi-gc">ffi.gc()</a></li>
<li><a class="reference internal" href="#ffi-new-handle-ffi-from-handle">ffi.new_handle(), ffi.from_handle()</a></li>
<li><a class="reference internal" href="#ffi-dlopen-ffi-dlclose">ffi.dlopen(), ffi.dlclose()</a></li>
<li><a class="reference internal" href="#ffi-new-allocator">ffi.new_allocator()</a></li>
<li><a class="reference internal" href="#ffi-init-once">ffi.init_once()</a></li>
<li><a class="reference internal" href="#ffi-getctype-ffi-list-types">ffi.getctype(), ffi.list_types()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conversions">Conversions</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="using.html"
 title="previous chapter">Using the ffi/lib objects</a>
 <h4>Next topic</h4>
 <a href="cdef.html"
 title="next chapter">Preparing and Distributing modules</a>
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/ref.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="cdef.html" title="Preparing and Distributing modules"
 >next</a> |</li>
 <li class="right" >
 <a href="using.html" title="Using the ffi/lib objects"
 >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>