170 lines
7.5 KiB
HTML
170 lines
7.5 KiB
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.
|
|
|
|
Copyright (C) 2008, 2010, 2011 Red Hat, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU General Public License as published by the
|
|
Free Software Foundation; either version 2, or (at your option) any
|
|
later version. A copy of the license is included in the
|
|
section entitled "GNU General Public License".
|
|
-->
|
|
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<title>The Basics (libffi)</title>
|
|
|
|
<meta name="description" content="The Basics (libffi)">
|
|
<meta name="keywords" content="The Basics (libffi)">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<link href="index.html#Top" rel="start" title="Top">
|
|
<link href="Index.html#Index" rel="index" title="Index">
|
|
<link href="Using-libffi.html#Using-libffi" rel="up" title="Using libffi">
|
|
<link href="Simple-Example.html#Simple-Example" rel="next" title="Simple Example">
|
|
<link href="Using-libffi.html#Using-libffi" rel="prev" title="Using libffi">
|
|
<style type="text/css">
|
|
<!--
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
|
blockquote.smallquotation {font-size: smaller}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
div.lisp {margin-left: 3.2em}
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
div.smallexample {margin-left: 3.2em}
|
|
div.smalllisp {margin-left: 3.2em}
|
|
kbd {font-style: oblique}
|
|
pre.display {font-family: inherit}
|
|
pre.format {font-family: inherit}
|
|
pre.menu-comment {font-family: serif}
|
|
pre.menu-preformatted {font-family: serif}
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
|
pre.smallexample {font-size: smaller}
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
|
pre.smalllisp {font-size: smaller}
|
|
span.nolinebreak {white-space: nowrap}
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<a name="The-Basics"></a>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Simple-Example.html#Simple-Example" accesskey="n" rel="next">Simple Example</a>, Up: <a href="Using-libffi.html#Using-libffi" accesskey="u" rel="up">Using libffi</a> [<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<a name="The-Basics-1"></a>
|
|
<h3 class="section">2.1 The Basics</h3>
|
|
|
|
<p>‘<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.
|
|
</p>
|
|
<p>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 <em>cif</em> in <code>ffi_cif</code> stands for
|
|
Call InterFace. To prepare a call interface object, use the function
|
|
<code>ffi_prep_cif</code>.
|
|
<a name="index-cif"></a>
|
|
</p>
|
|
<a name="index-ffi_005fprep_005fcif"></a>
|
|
<dl>
|
|
<dt><a name="index-ffi_005fstatus"></a>Function: <strong>ffi_status</strong> <em>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>)</em></dt>
|
|
<dd><p>This initializes <var>cif</var> according to the given parameters.
|
|
</p>
|
|
<p><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">Multiple ABIs</a> for more information.
|
|
</p>
|
|
<p><var>nargs</var> is the number of arguments that this function accepts.
|
|
</p>
|
|
<p><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">Types</a>.
|
|
</p>
|
|
<p><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.
|
|
</p>
|
|
<p><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.
|
|
</p></dd></dl>
|
|
|
|
<p>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>.
|
|
</p>
|
|
<a name="index-ffi_005fprep_005fcif_005fvar"></a>
|
|
<dl>
|
|
<dt><a name="index-ffi_005fstatus-1"></a>Function: <strong>ffi_status</strong> <em>ffi_prep_cif_var (ffi_cif *<var>cif</var>, ffi_abi varabi, unsigned int <var>nfixedargs</var>, unsigned int varntotalargs, ffi_type *<var>rtype</var>, ffi_type **<var>argtypes</var>)</em></dt>
|
|
<dd><p>This initializes <var>cif</var> according to the given parameters for
|
|
a call to a variadic function. In general it’s operation is the
|
|
same as for <code>ffi_prep_cif</code> except that:
|
|
</p>
|
|
<p><var>nfixedargs</var> is the number of fixed arguments, prior to any
|
|
variadic arguments. It must be greater than zero.
|
|
</p>
|
|
<p><var>ntotalargs</var> the total number of arguments, including variadic
|
|
and fixed arguments.
|
|
</p>
|
|
<p>Note that, different cif’s must be prepped for calls to the same
|
|
function when different numbers of arguments are passed.
|
|
</p>
|
|
<p>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>.
|
|
</p>
|
|
</dd></dl>
|
|
|
|
|
|
<p>To call a function using an initialized <code>ffi_cif</code>, use the
|
|
<code>ffi_call</code> function:
|
|
</p>
|
|
<a name="index-ffi_005fcall"></a>
|
|
<dl>
|
|
<dt><a name="index-void"></a>Function: <strong>void</strong> <em>ffi_call (ffi_cif *<var>cif</var>, void *<var>fn</var>, void *<var>rvalue</var>, void **<var>avalues</var>)</em></dt>
|
|
<dd><p>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>.
|
|
</p>
|
|
<p><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.
|
|
</p>
|
|
<p><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.
|
|
</p></dd></dl>
|
|
|
|
|
|
<hr>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Simple-Example.html#Simple-Example" accesskey="n" rel="next">Simple Example</a>, Up: <a href="Using-libffi.html#Using-libffi" accesskey="u" rel="up">Using libffi</a> [<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|