aboutsummaryrefslogtreecommitdiff
path: root/doc/ext_ffi_api.html
diff options
context:
space:
mode:
authorMike Pall <mike>2011-01-20 22:14:17 +0100
committerMike Pall <mike>2011-01-20 22:14:17 +0100
commite985aeda84d8af63c4bfaa176c3312dfb2f7f230 (patch)
tree8a68df0aac6779db0972bb9dc07fbbe0c7629bc7 /doc/ext_ffi_api.html
parent8396c3cdbc26e08fdf9dea204efb641dd6ad1f91 (diff)
downloadluajit-e985aeda84d8af63c4bfaa176c3312dfb2f7f230.tar.gz
luajit-e985aeda84d8af63c4bfaa176c3312dfb2f7f230.tar.bz2
luajit-e985aeda84d8af63c4bfaa176c3312dfb2f7f230.zip
FFI: Add preliminary FFI documentation (still incomplete).
Diffstat (limited to 'doc/ext_ffi_api.html')
-rw-r--r--doc/ext_ffi_api.html410
1 files changed, 410 insertions, 0 deletions
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html
new file mode 100644
index 00000000..f985d965
--- /dev/null
+++ b/doc/ext_ffi_api.html
@@ -0,0 +1,410 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>ffi.* API Functions</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6<meta name="Author" content="Mike Pall">
7<meta name="Copyright" content="Copyright (C) 2005-2011, Mike Pall">
8<meta name="Language" content="en">
9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11<style type="text/css">
12table.abitable { width: 30em; line-height: 1.2; }
13tr.abihead td { font-weight: bold; }
14td.abiparam { font-weight: bold; width: 6em; }
15</style>
16</head>
17<body>
18<div id="site">
19<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
20</div>
21<div id="head">
22<h1><tt>ffi.*</tt> API Functions</h1>
23</div>
24<div id="nav">
25<ul><li>
26<a href="luajit.html">LuaJIT</a>
27<ul><li>
28<a href="install.html">Installation</a>
29</li><li>
30<a href="running.html">Running</a>
31</li></ul>
32</li><li>
33<a href="extensions.html">Extensions</a>
34<ul><li>
35<a href="ext_ffi.html">FFI Library</a>
36<ul><li>
37<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
38</li><li>
39<a class="current" href="ext_ffi_api.html">ffi.* API</a>
40</li><li>
41<a href="ext_ffi_int64.html">64 bit Integers</a>
42</li><li>
43<a href="ext_ffi_semantics.html">FFI Semantics</a>
44</li></ul>
45</li><li>
46<a href="ext_jit.html">jit.* Library</a>
47</li><li>
48<a href="ext_c_api.html">Lua/C API</a>
49</li></ul>
50</li><li>
51<a href="status.html">Status</a>
52<ul><li>
53<a href="changes.html">Changes</a>
54</li></ul>
55</li><li>
56<a href="faq.html">FAQ</a>
57</li><li>
58<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
59</li><li>
60<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
61</li></ul>
62</div>
63<div id="main">
64<p>
65This page describes the API functions provided by the FFI library in
66detail. It's recommended to read through the
67<a href="ext_ffi.html">introduction</a> and the
68<a href="ext_ffi_tutorial.html">FFI tutorial</a> first.
69</p>
70
71<h2 id="glossary">Glossary</h2>
72<ul>
73<li><b>cdecl</b> &mdash; An abstract C&nbsp;type declaration (a Lua
74string).</li>
75<li><b>ctype</b> &mdash; A C&nbsp;type object. This is a special kind of
76<b>cdata</b> returned by <tt>ffi.typeof()</tt>. It serves as a
77<b>cdata</b> <a href="#ffi_new">constructor</a> when called.</li>
78<li><b>cdata</b> &mdash; A C&nbsp;data object. It holds a value of the
79corresponding <b>ctype</b>.</li>
80<li><b>ct</b> &mdash; A C&nbsp;type specification which can be used for
81most of the API functions. Either a <b>cdecl</b>, a <b>ctype</b> or a
82<b>cdata</b> serving as a template type.</li>
83<li><b>VLA</b> &mdash; A variable-length array is declared with a
84<tt>?</tt> instead of the number of elements, e.g. <tt>"int[?]"</tt>.
85The number of elements (<tt>nelem</tt>) must be given when it's
86<a href="#ffi_new">created</a>.</li>
87<li><b>VLS</b> &mdash; A variable-length struct is a <tt>struct</tt> C
88type where the last element is a <b>VLA</b>. The same rules for
89declaration and creation apply.</li>
90</ul>
91
92<h2 id="decl">Declaring and Accessing External Symbols</h2>
93<p>
94External symbols must be declared first and can then be accessed by
95indexing a <a href="ext_ffi_semantics.html#clib">C&nbsp;library
96namespace</a>, which automatically binds the symbol to a specific
97library.
98</p>
99
100<h3 id="ffi_cdef"><tt>ffi.cdef(def)</tt></h3>
101<p>
102Adds multiple C&nbsp;declarations for types or external symbols (named
103variables or functions). <tt>def</tt> must be a Lua string. It's
104recommended to use the syntactic sugar for string arguments as
105follows:
106</p>
107<pre class="code">
108ffi.cdef[[
109<span style="color:#00a000;font-weight:bold;">typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef.
110int dofoo(foo_t *f, int n); /* Declare an external C function. */</span>
111]]
112</pre>
113<p>
114The contents of the string (the part in green above) must be a
115sequence of
116<a href="ext_ffi_semantics.html#clang">C&nbsp;declarations</a>,
117separated by semicolons. The trailing semicolon for a single
118declaration may be omitted.
119</p>
120<p>
121Please note that external symbols are only <em>declared</em>, but they
122are <em>not bound</em> to any specific address, yet. Binding is
123achieved with C&nbsp;library namespaces (see below).
124</p>
125<p style="color: #c00000;">
126C&nbsp;declarations are not passed through a C&nbsp;pre-processor,
127yet. No pre-processor tokens are allowed, except for
128<tt>#pragma&nbsp;pack</tt>. Replace <tt>#define</tt> in existing
129C&nbsp;header files with <tt>enum</tt>, <tt>static&nbsp;const</tt>
130or <tt>typedef</tt> and/or pass the files through an external
131C&nbsp;pre-processor (once). Be careful not to include unneeded or
132redundant declarations from unrelated header files.
133</p>
134
135<h3 id="ffi_C"><tt>ffi.C</tt></h3>
136<p>
137This is the default C&nbsp;library namespace &mdash; note the
138uppercase <tt>'C'</tt>. It binds to the default set of symbols or
139libraries on the target system. These are more or less the same as a
140C&nbsp;compiler would offer by default, without specifying extra link
141libraries.
142</p>
143<p>
144On POSIX systems, this binds to symbols in the default or global
145namespace. This includes all exported symbols from the executable and
146any libraries loaded into the global namespace. This includes at least
147<tt>libc</tt>, <tt>libm</tt>, <tt>libdl</tt> (on Linux),
148<tt>libgcc</tt> (if compiled with GCC), as well as any exported
149symbols from the Lua/C&nbsp;API provided by LuaJIT itself.
150</p>
151<p>
152On Windows systems, this binds to symbols exported from the
153<tt>*.exe</tt>, the <tt>lua51.dll</tt> (i.e. the Lua/C&nbsp;API
154provided by LuaJIT itself), the C&nbsp;runtime library LuaJIT was linked
155with (<tt>msvcrt*.dll</tt>), <tt>kernel32.dll</tt>,
156<tt>user32.dll</tt> and <tt>gdi32.dll</tt>.
157</p>
158
159<h3 id="ffi_load"><tt>clib = ffi.load(name [,global])</tt></h3>
160<p>
161This loads the dynamic library given by <tt>name</tt> and returns
162a new C&nbsp;library namespace which binds to its symbols. On POSIX
163systems, if <tt>global</tt> is <tt>true</tt>, the library symbols are
164loaded into the global namespace, too.
165</p>
166<p>
167If <tt>name</tt> is a path, the library is loaded from this path.
168Otherwise <tt>name</tt> is canonicalized in a system-dependent way and
169searched in the default search path for dynamic libraries:
170</p>
171<p>
172On POSIX systems, if the name contains no dot, the extension
173<tt>.so</tt> is appended. Also, the <tt>lib</tt> prefix is prepended
174if necessary. So <tt>ffi.load("z")</tt> looks for <tt>"libz.so"</tt>
175in the default shared library search path.
176</p>
177<p>
178On Windows systems, if the name contains no dot, the extension
179<tt>.dll</tt> is appended. So <tt>ffi.load("ws2_32")</tt> looks for
180<tt>"ws2_32.dll"</tt> in the default DLL search path.
181</p>
182
183<h2 id="create">Creating cdata Objects</h2>
184<p>
185The following API functions create cdata objects (<tt>type()</tt>
186returns <tt>"cdata"</tt>). All created cdata objects are
187<a href="ext_ffi_semantics.html#gc">garbage collected</a>.
188</p>
189
190<h3 id="ffi_new"><tt>cdata = ffi.new(ct [,nelem] [,init...])<br>
191cdata = <em>ctype</em>([nelem,] [init...])</tt></h3>
192<p>
193Creates a cdata object for the given <tt>ct</tt>. VLA/VLS types
194require the <tt>nelem</tt> argument. The second syntax uses a ctype as
195a constructor and is otherwise fully equivalent.
196</p>
197<p>
198The <tt>init</tt> arguments provide optional initializers. The created
199cdata object is filled with zero bytes if no initializers are given.
200Scalar types accept a single initializer. Aggregates can either be
201initialized with a flat list of initializers or a single aggregate
202initializer (see the <a href="ext_ffi_semantics.html#convert">C&nbsp;type
203conversion rules</a>). Excess initializers cause an error.
204</p>
205<p>
206If a single initializer is given for an array, it's repeated for all
207remaining elements. This doesn't happen if two or more initializers
208are given &mdash; all uninitialized elements are filled with zero
209bytes. The fields of a <tt>struct</tt> are initialized in the order of
210their declaration. Uninitialized fields are filled with zero bytes.
211Only the first field of <tt>union</tt> can be initialized with a flat
212initializer. Elements or fields which are aggregates themselves are
213initialized with a <em>single</em> <tt>init</tt> argument, but this
214may be an aggregate initializer of course.
215</p>
216<p>
217Performance notice: if you want to create many objects of one kind,
218parse the cdecl only once and get its ctype with
219<tt>ffi.typeof()</tt>. Then use the ctype as a constructor repeatedly.
220</p>
221<p style="font-size: 8pt;">
222Please note that an anonymous <tt>struct</tt> declaration implicitly
223creates a new and distinguished ctype every time you use it for
224<tt>ffi.new()</tt>. This is probably <b>not</b> what you want,
225especially if you create more than one cdata object. Different anonymous
226<tt>structs</tt> are not considered assignment-compatible by the
227C&nbsp;standard, even though they may have the same fields! Also, they
228are considered different types by the JIT-compiler, which may cause an
229excessive number of traces. It's strongly suggested to either declare
230a named <tt>struct</tt> or <tt>typedef</tt> with <tt>ffi.cdef()</tt>
231or to create a single ctype object for an anonymous <tt>struct</tt>
232with <tt>ffi.typeof()</tt>.
233</p>
234
235<h3 id="ffi_typeof"><tt>ctype = ffi.typeof(ct)</tt></h3>
236<p>
237Creates a ctype object for the given <tt>ct</tt>.
238</p>
239<p>
240This function is especially useful to parse a cdecl only once and then
241use the resulting ctype object as a <a href="#ffi_new">constructor</a>.
242</p>
243
244<h3 id="ffi_cast"><tt>cdata = ffi.cast(ct, init)</tt></h3>
245<p>
246Creates a scalar cdata object for the given <tt>ct</tt>. The cdata
247object is initialized with <tt>init</tt> using the "cast" variant of
248the <a href="ext_ffi_semantics.html#convert">C&nbsp;type conversion
249rules</a>.
250</p>
251<p>
252This functions is mainly useful to override the pointer compatibility
253rules or to convert pointers to addresses or vice versa. For maximum
254portability you should convert a pointer to its address as follows:
255</p>
256<pre class="code">
257local addr = tonumber(ffi.cast("intptr_t", ptr))
258</pre>
259
260<h2 id="info">C&nbsp;Type Information</h2>
261<p>
262The following API functions return information about C&nbsp;types.
263They are most useful for inspecting cdata objects.
264</p>
265
266<h3 id="ffi_sizeof"><tt>size = ffi.sizeof(ct [,nelem])</tt></h3>
267<p>
268Returns the size of <tt>ct</tt> in bytes. Returns <tt>nil</tt> if
269the size is not known (e.g. for <tt>"void"</tt> or function types).
270Requires <tt>nelem</tt> for VLA/VLS types, except for cdata objects.
271</p>
272
273<h3 id="ffi_alignof"><tt>align = ffi.alignof(ct)</tt></h3>
274<p>
275Returns the minimum required alignment for <tt>ct</tt> in bytes.
276</p>
277
278<h3 id="ffi_offsetof"><tt>ofs [,bpos,bsize] = ffi.offsetof(ct, field)</tt></h3>
279<p>
280Returns the offset (in bytes) of <tt>field</tt> relative to the start
281of <tt>ct</tt>, which must be a <tt>struct</tt>. Additionally returns
282the position and the field size (in bits) for bit fields.
283</p>
284
285<h2 id="util">Utility Functions</h2>
286
287<h3 id="ffi_string"><tt>str = ffi.string(ptr [,len])</tt></h3>
288<p>
289Creates an interned Lua string from the data pointed to by
290<tt>ptr</tt>.
291</p>
292<p>
293If the optional argument <tt>len</tt> is missing, <tt>ptr</tt> is
294converted to a <tt>"char&nbsp;*"</tt> and the data is assumed to be
295zero-terminated. The length of the string is computed with
296<tt>strlen()</tt>.
297</p>
298<p>
299Otherwise <tt>ptr</tt> is converted to a <tt>"void&nbsp;*"</tt> and
300<tt>len</tt> gives the length of the data. The data may contain
301embedded zeros and need not be byte-oriented (though this may cause
302endianess issues).
303</p>
304<p>
305This function is mainly useful to convert (temporary)
306<tt>"const&nbsp;char&nbsp;*"</tt> pointers returned by
307C&nbsp;functions to Lua strings and store them or pass them to other
308functions expecting a Lua string. The Lua string is an (interned) copy
309of the data and bears no relation to the original data area anymore.
310Lua strings are 8&nbsp;bit clean and may be used to hold arbitrary,
311non-character data.
312</p>
313<p>
314Performance notice: it's faster to pass the length of the string, if
315it's known. E.g. when the length is returned by a C&nbsp;call like
316<tt>sprintf()</tt>.
317</p>
318
319<h3 id="ffi_copy"><tt>ffi.copy(dst, src, len)<br>
320ffi.copy(dst, str)</tt></h3>
321<p>
322Copies the data pointed to by <tt>src</tt> to <tt>dst</tt>.
323<tt>dst</tt> is converted to a <tt>"void&nbsp;*"</tt> and <tt>src</tt>
324is converted to a <tt>"const void&nbsp;*"</tt>.
325</p>
326<p>
327In the first syntax, <tt>len</tt> gives the number of bytes to copy.
328In case <tt>src</tt> is a Lua string, the maximum copy length is the
329number of bytes of the string plus a zero-terminator. Caveat: the
330copied data may not be zero-terminated if <tt>len&nbsp;&le;&nbsp;#src</tt>.
331</p>
332<p>
333In the second syntax, the source of the copy must be a Lua string. All
334bytes of the string plus a zero-terminator are copied to <tt>dst</tt>.
335</p>
336<p>
337Performance notice: <tt>ffi.copy()</tt> may be used as a faster
338(inlineable) replacement for the C&nbsp;library functions
339<tt>memcpy()</tt>, <tt>strcpy()</tt> and <tt>strncpy()</tt>.
340</p>
341
342<h3 id="ffi_fill"><tt>ffi.fill(dst, len [,c])</tt></h3>
343<p>
344Fills the data pointed to by <tt>dst</tt> with <tt>len</tt> constant
345bytes, given by <tt>c</tt>. If <tt>c</tt> is omitted, the data is
346zero-filled.
347</p>
348<p>
349Performance notice: <tt>ffi.fill()</tt> may be used as a faster
350(inlineable) replacement for the C&nbsp;library function
351<tt>memset(dst,&nbsp;c,&nbsp;len)</tt>. Please note the different
352order of arguments!
353</p>
354
355<h2 id="target">Target-specific Information</h2>
356
357<h3 id="ffi_abi"><tt>status = ffi.abi(param)</tt></h3>
358<p>
359Returns <tt>true</tt> if <tt>param</tt> (a Lua string) applies for the
360target ABI (Application Binary Interface). Otherwise returns
361<tt>false</tt>. The following parameters are currently defined:
362</p>
363<table class="abitable">
364<tr class="abihead">
365<td class="abiparam">Parameter</td>
366<td class="abidesc">Description</td>
367</tr>
368<tr class="odd separate">
369<td class="abiparam">32bit</td><td class="abidesc">32 bit architecture</td></tr>
370<tr class="even">
371<td class="abiparam">64bit</td><td class="abidesc">64 bit architecture</td></tr>
372<tr class="odd separate">
373<td class="abiparam">le</td><td class="abidesc">Little-endian architecture</td></tr>
374<tr class="even">
375<td class="abiparam">be</td><td class="abidesc">Big-endian architecture</td></tr>
376<tr class="odd separate">
377<td class="abiparam">fpu</td><td class="abidesc">Target has a hardware FPU</td></tr>
378<tr class="even">
379<td class="abiparam">softfp</td><td class="abidesc">softfp calling conventions</td></tr>
380<tr class="odd">
381<td class="abiparam">hardfp</td><td class="abidesc">hardfp calling conventions</td></tr>
382<tr class="even separate">
383<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr>
384<tr class="odd">
385<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr>
386</table>
387
388<h3 id="ffi_os"><tt>ffi.os</tt></h3>
389<p>
390Contains the target OS name. Same contents as
391<a href="ext_jit.html#jit_os"><tt>jit.os</tt></a>.
392</p>
393
394<h3 id="ffi_arch"><tt>ffi.arch</tt></h3>
395<p>
396Contains the target architecture name. Same contents as
397<a href="ext_jit.html#jit_arch"><tt>jit.arch</tt></a>.
398</p>
399<br class="flush">
400</div>
401<div id="foot">
402<hr class="hide">
403Copyright &copy; 2005-2011 Mike Pall
404<span class="noprint">
405&middot;
406<a href="contact.html">Contact</a>
407</span>
408</div>
409</body>
410</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-12 07:37:40 +0000