mirror of
https://github.com/LuaJIT/LuaJIT.git
synced 2025-02-07 15:14:08 +00:00
431 lines
16 KiB
HTML
431 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>ffi.* API Functions</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="Author" content="Mike Pall">
|
|
<meta name="Copyright" content="Copyright (C) 2005-2011, Mike Pall">
|
|
<meta name="Language" content="en">
|
|
<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
|
|
<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
|
|
<style type="text/css">
|
|
table.abitable { width: 30em; line-height: 1.2; }
|
|
tr.abihead td { font-weight: bold; }
|
|
td.abiparam { font-weight: bold; width: 6em; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div id="site">
|
|
<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
|
|
</div>
|
|
<div id="head">
|
|
<h1><tt>ffi.*</tt> API Functions</h1>
|
|
</div>
|
|
<div id="nav">
|
|
<ul><li>
|
|
<a href="luajit.html">LuaJIT</a>
|
|
<ul><li>
|
|
<a href="install.html">Installation</a>
|
|
</li><li>
|
|
<a href="running.html">Running</a>
|
|
</li></ul>
|
|
</li><li>
|
|
<a href="extensions.html">Extensions</a>
|
|
<ul><li>
|
|
<a href="ext_ffi.html">FFI Library</a>
|
|
<ul><li>
|
|
<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
|
|
</li><li>
|
|
<a class="current" href="ext_ffi_api.html">ffi.* API</a>
|
|
</li><li>
|
|
<a href="ext_ffi_semantics.html">FFI Semantics</a>
|
|
</li></ul>
|
|
</li><li>
|
|
<a href="ext_jit.html">jit.* Library</a>
|
|
</li><li>
|
|
<a href="ext_c_api.html">Lua/C API</a>
|
|
</li></ul>
|
|
</li><li>
|
|
<a href="status.html">Status</a>
|
|
<ul><li>
|
|
<a href="changes.html">Changes</a>
|
|
</li></ul>
|
|
</li><li>
|
|
<a href="faq.html">FAQ</a>
|
|
</li><li>
|
|
<a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a>
|
|
</li><li>
|
|
<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a>
|
|
</li></ul>
|
|
</div>
|
|
<div id="main">
|
|
<p>
|
|
This page describes the API functions provided by the FFI library in
|
|
detail. It's recommended to read through the
|
|
<a href="ext_ffi.html">introduction</a> and the
|
|
<a href="ext_ffi_tutorial.html">FFI tutorial</a> first.
|
|
</p>
|
|
|
|
<h2 id="glossary">Glossary</h2>
|
|
<ul>
|
|
<li><b>cdecl</b> — An abstract C type declaration (a Lua
|
|
string).</li>
|
|
<li><b>ctype</b> — A C type object. This is a special kind of
|
|
<b>cdata</b> returned by <tt>ffi.typeof()</tt>. It serves as a
|
|
<b>cdata</b> <a href="#ffi_new">constructor</a> when called.</li>
|
|
<li><b>cdata</b> — A C data object. It holds a value of the
|
|
corresponding <b>ctype</b>.</li>
|
|
<li><b>ct</b> — A C type specification which can be used for
|
|
most of the API functions. Either a <b>cdecl</b>, a <b>ctype</b> or a
|
|
<b>cdata</b> serving as a template type.</li>
|
|
<li><b>VLA</b> — A variable-length array is declared with a
|
|
<tt>?</tt> instead of the number of elements, e.g. <tt>"int[?]"</tt>.
|
|
The number of elements (<tt>nelem</tt>) must be given when it's
|
|
<a href="#ffi_new">created</a>.</li>
|
|
<li><b>VLS</b> — A variable-length struct is a <tt>struct</tt> C
|
|
type where the last element is a <b>VLA</b>. The same rules for
|
|
declaration and creation apply.</li>
|
|
</ul>
|
|
|
|
<h2 id="decl">Declaring and Accessing External Symbols</h2>
|
|
<p>
|
|
External symbols must be declared first and can then be accessed by
|
|
indexing a <a href="ext_ffi_semantics.html#clib">C library
|
|
namespace</a>, which automatically binds the symbol to a specific
|
|
library.
|
|
</p>
|
|
|
|
<h3 id="ffi_cdef"><tt>ffi.cdef(def)</tt></h3>
|
|
<p>
|
|
Adds multiple C declarations for types or external symbols (named
|
|
variables or functions). <tt>def</tt> must be a Lua string. It's
|
|
recommended to use the syntactic sugar for string arguments as
|
|
follows:
|
|
</p>
|
|
<pre class="code">
|
|
ffi.cdef[[
|
|
<span style="color:#00a000;">typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef.
|
|
int dofoo(foo_t *f, int n); /* Declare an external C function. */</span>
|
|
]]
|
|
</pre>
|
|
<p>
|
|
The contents of the string (the part in green above) must be a
|
|
sequence of
|
|
<a href="ext_ffi_semantics.html#clang">C declarations</a>,
|
|
separated by semicolons. The trailing semicolon for a single
|
|
declaration may be omitted.
|
|
</p>
|
|
<p>
|
|
Please note that external symbols are only <em>declared</em>, but they
|
|
are <em>not bound</em> to any specific address, yet. Binding is
|
|
achieved with C library namespaces (see below).
|
|
</p>
|
|
<p style="color: #c00000;">
|
|
C declarations are not passed through a C pre-processor,
|
|
yet. No pre-processor tokens are allowed, except for
|
|
<tt>#pragma pack</tt>. Replace <tt>#define</tt> in existing
|
|
C header files with <tt>enum</tt>, <tt>static const</tt>
|
|
or <tt>typedef</tt> and/or pass the files through an external
|
|
C pre-processor (once). Be careful not to include unneeded or
|
|
redundant declarations from unrelated header files.
|
|
</p>
|
|
|
|
<h3 id="ffi_C"><tt>ffi.C</tt></h3>
|
|
<p>
|
|
This is the default C library namespace — note the
|
|
uppercase <tt>'C'</tt>. It binds to the default set of symbols or
|
|
libraries on the target system. These are more or less the same as a
|
|
C compiler would offer by default, without specifying extra link
|
|
libraries.
|
|
</p>
|
|
<p>
|
|
On POSIX systems, this binds to symbols in the default or global
|
|
namespace. This includes all exported symbols from the executable and
|
|
any libraries loaded into the global namespace. This includes at least
|
|
<tt>libc</tt>, <tt>libm</tt>, <tt>libdl</tt> (on Linux),
|
|
<tt>libgcc</tt> (if compiled with GCC), as well as any exported
|
|
symbols from the Lua/C API provided by LuaJIT itself.
|
|
</p>
|
|
<p>
|
|
On Windows systems, this binds to symbols exported from the
|
|
<tt>*.exe</tt>, the <tt>lua51.dll</tt> (i.e. the Lua/C API
|
|
provided by LuaJIT itself), the C runtime library LuaJIT was linked
|
|
with (<tt>msvcrt*.dll</tt>), <tt>kernel32.dll</tt>,
|
|
<tt>user32.dll</tt> and <tt>gdi32.dll</tt>.
|
|
</p>
|
|
|
|
<h3 id="ffi_load"><tt>clib = ffi.load(name [,global])</tt></h3>
|
|
<p>
|
|
This loads the dynamic library given by <tt>name</tt> and returns
|
|
a new C library namespace which binds to its symbols. On POSIX
|
|
systems, if <tt>global</tt> is <tt>true</tt>, the library symbols are
|
|
loaded into the global namespace, too.
|
|
</p>
|
|
<p>
|
|
If <tt>name</tt> is a path, the library is loaded from this path.
|
|
Otherwise <tt>name</tt> is canonicalized in a system-dependent way and
|
|
searched in the default search path for dynamic libraries:
|
|
</p>
|
|
<p>
|
|
On POSIX systems, if the name contains no dot, the extension
|
|
<tt>.so</tt> is appended. Also, the <tt>lib</tt> prefix is prepended
|
|
if necessary. So <tt>ffi.load("z")</tt> looks for <tt>"libz.so"</tt>
|
|
in the default shared library search path.
|
|
</p>
|
|
<p>
|
|
On Windows systems, if the name contains no dot, the extension
|
|
<tt>.dll</tt> is appended. So <tt>ffi.load("ws2_32")</tt> looks for
|
|
<tt>"ws2_32.dll"</tt> in the default DLL search path.
|
|
</p>
|
|
|
|
<h2 id="create">Creating cdata Objects</h2>
|
|
<p>
|
|
The following API functions create cdata objects (<tt>type()</tt>
|
|
returns <tt>"cdata"</tt>). All created cdata objects are
|
|
<a href="ext_ffi_semantics.html#gc">garbage collected</a>.
|
|
</p>
|
|
|
|
<h3 id="ffi_new"><tt>cdata = ffi.new(ct [,nelem] [,init...])<br>
|
|
cdata = <em>ctype</em>([nelem,] [init...])</tt></h3>
|
|
<p>
|
|
Creates a cdata object for the given <tt>ct</tt>. VLA/VLS types
|
|
require the <tt>nelem</tt> argument. The second syntax uses a ctype as
|
|
a constructor and is otherwise fully equivalent.
|
|
</p>
|
|
<p>
|
|
The cdata object is initialized according to the
|
|
<a href="ext_ffi_semantics.html#init">rules for initializers</a>,
|
|
using the optional <tt>init</tt> arguments. Excess initializers cause
|
|
an error.
|
|
</p>
|
|
<p>
|
|
Performance notice: if you want to create many objects of one kind,
|
|
parse the cdecl only once and get its ctype with
|
|
<tt>ffi.typeof()</tt>. Then use the ctype as a constructor repeatedly.
|
|
</p>
|
|
<p style="font-size: 8pt;">
|
|
Please note that an anonymous <tt>struct</tt> declaration implicitly
|
|
creates a new and distinguished ctype every time you use it for
|
|
<tt>ffi.new()</tt>. This is probably <b>not</b> what you want,
|
|
especially if you create more than one cdata object. Different anonymous
|
|
<tt>structs</tt> are not considered assignment-compatible by the
|
|
C standard, even though they may have the same fields! Also, they
|
|
are considered different types by the JIT-compiler, which may cause an
|
|
excessive number of traces. It's strongly suggested to either declare
|
|
a named <tt>struct</tt> or <tt>typedef</tt> with <tt>ffi.cdef()</tt>
|
|
or to create a single ctype object for an anonymous <tt>struct</tt>
|
|
with <tt>ffi.typeof()</tt>.
|
|
</p>
|
|
|
|
<h3 id="ffi_typeof"><tt>ctype = ffi.typeof(ct)</tt></h3>
|
|
<p>
|
|
Creates a ctype object for the given <tt>ct</tt>.
|
|
</p>
|
|
<p>
|
|
This function is especially useful to parse a cdecl only once and then
|
|
use the resulting ctype object as a <a href="#ffi_new">constructor</a>.
|
|
</p>
|
|
|
|
<h3 id="ffi_cast"><tt>cdata = ffi.cast(ct, init)</tt></h3>
|
|
<p>
|
|
Creates a scalar cdata object for the given <tt>ct</tt>. The cdata
|
|
object is initialized with <tt>init</tt> using the "cast" variant of
|
|
the <a href="ext_ffi_semantics.html#convert">C type conversion
|
|
rules</a>.
|
|
</p>
|
|
<p>
|
|
This functions is mainly useful to override the pointer compatibility
|
|
checks or to convert pointers to addresses or vice versa.
|
|
</p>
|
|
|
|
<h2 id="info">C Type Information</h2>
|
|
<p>
|
|
The following API functions return information about C types.
|
|
They are most useful for inspecting cdata objects.
|
|
</p>
|
|
|
|
<h3 id="ffi_sizeof"><tt>size = ffi.sizeof(ct [,nelem])</tt></h3>
|
|
<p>
|
|
Returns the size of <tt>ct</tt> in bytes. Returns <tt>nil</tt> if
|
|
the size is not known (e.g. for <tt>"void"</tt> or function types).
|
|
Requires <tt>nelem</tt> for VLA/VLS types, except for cdata objects.
|
|
</p>
|
|
|
|
<h3 id="ffi_alignof"><tt>align = ffi.alignof(ct)</tt></h3>
|
|
<p>
|
|
Returns the minimum required alignment for <tt>ct</tt> in bytes.
|
|
</p>
|
|
|
|
<h3 id="ffi_offsetof"><tt>ofs [,bpos,bsize] = ffi.offsetof(ct, field)</tt></h3>
|
|
<p>
|
|
Returns the offset (in bytes) of <tt>field</tt> relative to the start
|
|
of <tt>ct</tt>, which must be a <tt>struct</tt>. Additionally returns
|
|
the position and the field size (in bits) for bit fields.
|
|
</p>
|
|
|
|
<h2 id="util">Utility Functions</h2>
|
|
|
|
<h3 id="ffi_string"><tt>str = ffi.string(ptr [,len])</tt></h3>
|
|
<p>
|
|
Creates an interned Lua string from the data pointed to by
|
|
<tt>ptr</tt>.
|
|
</p>
|
|
<p>
|
|
If the optional argument <tt>len</tt> is missing, <tt>ptr</tt> is
|
|
converted to a <tt>"char *"</tt> and the data is assumed to be
|
|
zero-terminated. The length of the string is computed with
|
|
<tt>strlen()</tt>.
|
|
</p>
|
|
<p>
|
|
Otherwise <tt>ptr</tt> is converted to a <tt>"void *"</tt> and
|
|
<tt>len</tt> gives the length of the data. The data may contain
|
|
embedded zeros and need not be byte-oriented (though this may cause
|
|
endianess issues).
|
|
</p>
|
|
<p>
|
|
This function is mainly useful to convert (temporary)
|
|
<tt>"const char *"</tt> pointers returned by
|
|
C functions to Lua strings and store them or pass them to other
|
|
functions expecting a Lua string. The Lua string is an (interned) copy
|
|
of the data and bears no relation to the original data area anymore.
|
|
Lua strings are 8 bit clean and may be used to hold arbitrary,
|
|
non-character data.
|
|
</p>
|
|
<p>
|
|
Performance notice: it's faster to pass the length of the string, if
|
|
it's known. E.g. when the length is returned by a C call like
|
|
<tt>sprintf()</tt>.
|
|
</p>
|
|
|
|
<h3 id="ffi_copy"><tt>ffi.copy(dst, src, len)<br>
|
|
ffi.copy(dst, str)</tt></h3>
|
|
<p>
|
|
Copies the data pointed to by <tt>src</tt> to <tt>dst</tt>.
|
|
<tt>dst</tt> is converted to a <tt>"void *"</tt> and <tt>src</tt>
|
|
is converted to a <tt>"const void *"</tt>.
|
|
</p>
|
|
<p>
|
|
In the first syntax, <tt>len</tt> gives the number of bytes to copy.
|
|
Caveat: if <tt>src</tt> is a Lua string, then <tt>len</tt> must not
|
|
exceed <tt>#src+1</tt>.
|
|
</p>
|
|
<p>
|
|
In the second syntax, the source of the copy must be a Lua string. All
|
|
bytes of the string <em>plus a zero-terminator</em> are copied to
|
|
<tt>dst</tt> (i.e. <tt>#src+1</tt> bytes).
|
|
</p>
|
|
<p>
|
|
Performance notice: <tt>ffi.copy()</tt> may be used as a faster
|
|
(inlineable) replacement for the C library functions
|
|
<tt>memcpy()</tt>, <tt>strcpy()</tt> and <tt>strncpy()</tt>.
|
|
</p>
|
|
|
|
<h3 id="ffi_fill"><tt>ffi.fill(dst, len [,c])</tt></h3>
|
|
<p>
|
|
Fills the data pointed to by <tt>dst</tt> with <tt>len</tt> constant
|
|
bytes, given by <tt>c</tt>. If <tt>c</tt> is omitted, the data is
|
|
zero-filled.
|
|
</p>
|
|
<p>
|
|
Performance notice: <tt>ffi.fill()</tt> may be used as a faster
|
|
(inlineable) replacement for the C library function
|
|
<tt>memset(dst, c, len)</tt>. Please note the different
|
|
order of arguments!
|
|
</p>
|
|
|
|
<h2 id="target">Target-specific Information</h2>
|
|
|
|
<h3 id="ffi_abi"><tt>status = ffi.abi(param)</tt></h3>
|
|
<p>
|
|
Returns <tt>true</tt> if <tt>param</tt> (a Lua string) applies for the
|
|
target ABI (Application Binary Interface). Returns <tt>false</tt>
|
|
otherwise. The following parameters are currently defined:
|
|
</p>
|
|
<table class="abitable">
|
|
<tr class="abihead">
|
|
<td class="abiparam">Parameter</td>
|
|
<td class="abidesc">Description</td>
|
|
</tr>
|
|
<tr class="odd separate">
|
|
<td class="abiparam">32bit</td><td class="abidesc">32 bit architecture</td></tr>
|
|
<tr class="even">
|
|
<td class="abiparam">64bit</td><td class="abidesc">64 bit architecture</td></tr>
|
|
<tr class="odd separate">
|
|
<td class="abiparam">le</td><td class="abidesc">Little-endian architecture</td></tr>
|
|
<tr class="even">
|
|
<td class="abiparam">be</td><td class="abidesc">Big-endian architecture</td></tr>
|
|
<tr class="odd separate">
|
|
<td class="abiparam">fpu</td><td class="abidesc">Target has a hardware FPU</td></tr>
|
|
<tr class="even">
|
|
<td class="abiparam">softfp</td><td class="abidesc">softfp calling conventions</td></tr>
|
|
<tr class="odd">
|
|
<td class="abiparam">hardfp</td><td class="abidesc">hardfp calling conventions</td></tr>
|
|
<tr class="even separate">
|
|
<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr>
|
|
<tr class="odd">
|
|
<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr>
|
|
</table>
|
|
|
|
<h3 id="ffi_os"><tt>ffi.os</tt></h3>
|
|
<p>
|
|
Contains the target OS name. Same contents as
|
|
<a href="ext_jit.html#jit_os"><tt>jit.os</tt></a>.
|
|
</p>
|
|
|
|
<h3 id="ffi_arch"><tt>ffi.arch</tt></h3>
|
|
<p>
|
|
Contains the target architecture name. Same contents as
|
|
<a href="ext_jit.html#jit_arch"><tt>jit.arch</tt></a>.
|
|
</p>
|
|
|
|
<h2 id="extended">Extended Standard Library Functions</h2>
|
|
<p>
|
|
The following standard library functions have been extended to work
|
|
with cdata objects:
|
|
</p>
|
|
|
|
<h3 id="tonumber"><tt>n = tonumber(cdata)</tt></h3>
|
|
<p>
|
|
Converts a number cdata object to a <tt>double</tt> and returns it as
|
|
a Lua number. This is particularly useful for boxed 64 bit
|
|
integer values. Caveat: this conversion may incur a precision loss.
|
|
</p>
|
|
|
|
<h3 id="tostring"><tt>s = tostring(cdata)</tt></h3>
|
|
<p>
|
|
Returns a string representation of the value of 64 bit integers
|
|
(<tt><b>"</b>nnn<b>LL"</b></tt> or <tt><b>"</b>nnn<b>ULL"</b></tt>) or
|
|
complex numbers (<tt><b>"</b>re±im<b>i"</b></tt>). Otherwise
|
|
returns a string representation of the C type of a ctype object
|
|
(<tt><b>"ctype<</b>type<b>>"</b></tt>) or a cdata object
|
|
(<tt><b>"cdata<</b>type<b>>: </b>address"</tt>).
|
|
</p>
|
|
|
|
<h2 id="literals">Extensions to the Lua Parser</h2>
|
|
<p>
|
|
The parser for Lua source code treats numeric literals with the
|
|
suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64 bit
|
|
integers. Case doesn't matter, but uppercase is recommended for
|
|
readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal
|
|
(<tt>0x2aLL</tt>) literals.
|
|
</p>
|
|
<p>
|
|
The imaginary part of complex numbers can be specified by suffixing
|
|
number literals with <tt>i</tt> or <tt>I</tt>, e.g. <tt>12.5i</tt>.
|
|
Caveat: you'll need to use <tt>1i</tt> to get an imaginary part with
|
|
the value one, since <tt>i</tt> itself still refers to a variable
|
|
named <tt>i</tt>.
|
|
</p>
|
|
<br class="flush">
|
|
</div>
|
|
<div id="foot">
|
|
<hr class="hide">
|
|
Copyright © 2005-2011 Mike Pall
|
|
<span class="noprint">
|
|
·
|
|
<a href="contact.html">Contact</a>
|
|
</span>
|
|
</div>
|
|
</body>
|
|
</html>
|