Default page

Edit File: The-Basics.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- 
This manual is for libffi, a portable foreign function interface
library.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 -->

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>The Basics (libffi: the portable foreign function interface library)</title>

</head>

<body lang="en">
<div class="header">

Next: <a href="Simple-Example.html" accesskey="n" rel="next">Simple Example</a>, Up: <a href="Using-libffi.html" accesskey="u" rel="up">Using libffi</a>   [<a href="Index.html" title="Index" rel="index">Index</a>]
</div>
<hr>
<h3 class="section">2.1 The Basics</h3>

‘<samp>Libffi</samp>’ assumes that you have a pointer to the function you wish
to call and that you know the number and types of arguments to pass
it, as well as the return type of the function.

The first thing you must do is create an <code>ffi_cif</code> object that
matches the signature of the function you wish to call. This is a
separate step because it is common to make multiple calls using a
single <code>ffi_cif</code>. The cif in <code>ffi_cif</code> stands for
Call InterFace. To prepare a call interface object, use the function
<code>ffi_prep_cif</code>.



<dl>
<dt id="index-ffi_005fstatus">Function: ffi_status ffi_prep_cif (ffi_cif *<var>cif</var>, ffi_abi <var>abi</var>, unsigned int <var>nargs</var>, ffi_type *<var>rtype</var>, ffi_type **<var>argtypes</var>)</dt>
<dd>This initializes <var>cif</var> according to the given parameters.

<var>abi</var> is the ABI to use; normally <code>FFI_DEFAULT_ABI</code> is what
you want. <a href="Multiple-ABIs.html">Multiple ABIs</a> for more information.

<var>nargs</var> is the number of arguments that this function accepts.

<var>rtype</var> is a pointer to an <code>ffi_type</code> structure that
describes the return type of the function. See <a href="Types.html">Types</a>.

<var>argtypes</var> is a vector of <code>ffi_type</code> pointers.
<var>argtypes</var> must have <var>nargs</var> elements. If <var>nargs</var> is 0,
this argument is ignored.

<code>ffi_prep_cif</code> returns a <code>libffi</code> status code, of type
<code>ffi_status</code>. This will be either <code>FFI_OK</code> if everything
worked properly; <code>FFI_BAD_TYPEDEF</code> if one of the <code>ffi_type</code>
objects is incorrect; or <code>FFI_BAD_ABI</code> if the <var>abi</var> parameter
is invalid.
</dd></dl>

If the function being called is variadic (varargs) then
<code>ffi_prep_cif_var</code> must be used instead of <code>ffi_prep_cif</code>.


<dl>
<dt id="index-ffi_005fstatus-1">Function: ffi_status ffi_prep_cif_var (ffi_cif *<var>cif</var>, ffi_abi <var>abi</var>, unsigned int <var>nfixedargs</var>, unsigned int <var>ntotalargs</var>, ffi_type *<var>rtype</var>, ffi_type **<var>argtypes</var>)</dt>
<dd>This initializes <var>cif</var> according to the given parameters for
a call to a variadic function. In general its operation is the
same as for <code>ffi_prep_cif</code> except that:

<var>nfixedargs</var> is the number of fixed arguments, prior to any
variadic arguments. It must be greater than zero.

<var>ntotalargs</var> the total number of arguments, including variadic
and fixed arguments. <var>argtypes</var> must have this many elements.

Note that, different cif’s must be prepped for calls to the same
function when different numbers of arguments are passed.

Also note that a call to <code>ffi_prep_cif_var</code> with
<var>nfixedargs</var>=<var>nototalargs</var> is NOT equivalent to a call to
<code>ffi_prep_cif</code>.

</dd></dl>

Note that the resulting <code>ffi_cif</code> holds pointers to all the
<code>ffi_type</code> objects that were used during initialization. You
must ensure that these type objects have a lifetime at least as long
as that of the <code>ffi_cif</code>.

To call a function using an initialized <code>ffi_cif</code>, use the
<code>ffi_call</code> function:


<dl>
<dt id="index-void">Function: void ffi_call (ffi_cif *<var>cif</var>, void *<var>fn</var>, void *<var>rvalue</var>, void **<var>avalues</var>)</dt>
<dd>This calls the function <var>fn</var> according to the description given in
<var>cif</var>. <var>cif</var> must have already been prepared using
<code>ffi_prep_cif</code>.

<var>rvalue</var> is a pointer to a chunk of memory that will hold the
result of the function call. This must be large enough to hold the
result, no smaller than the system register size (generally 32 or 64
bits), and must be suitably aligned; it is the caller’s responsibility
to ensure this. If <var>cif</var> declares that the function returns
<code>void</code> (using <code>ffi_type_void</code>), then <var>rvalue</var> is
ignored.

In most situations, ‘<samp>libffi</samp>’ will handle promotion according to
the ABI. However, for historical reasons, there is a special case
with return values that must be handled by your code. In particular,
for integral (not <code>struct</code>) types that are narrower than the
system register size, the return value will be widened by
‘<samp>libffi</samp>’. ‘<samp>libffi</samp>’ provides a type, <code>ffi_arg</code>, that
can be used as the return type. For example, if the CIF was defined
with a return type of <code>char</code>, ‘<samp>libffi</samp>’ will try to store a
full <code>ffi_arg</code> into the return value.

<var>avalues</var> is a vector of <code>void *</code> pointers that point to the
memory locations holding the argument values for a call. If <var>cif</var>
declares that the function has no arguments (i.e., <var>nargs</var> was 0),
then <var>avalues</var> is ignored. Note that argument values may be
modified by the callee (for instance, structs passed by value); the
burden of copying pass-by-value arguments is placed on the caller.

Note that while the return value must be register-sized, arguments
should exactly match their declared type. For example, if an argument
is a <code>short</code>, then the entry in <var>avalues</var> should point to an
object declared as <code>short</code>; but if the return type is
<code>short</code>, then <var>rvalue</var> should point to an object declared as
a larger type – usually <code>ffi_arg</code>.
</dd></dl>

<hr>
<div class="header">

Next: <a href="Simple-Example.html" accesskey="n" rel="next">Simple Example</a>, Up: <a href="Using-libffi.html" accesskey="u" rel="up">Using libffi</a>   [<a href="Index.html" title="Index" rel="index">Index</a>]
</div>

</body>
</html>