aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/luajit-2.0/doc/ext_ffi_semantics.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/luajit-2.0/doc/ext_ffi_semantics.html')
-rw-r--r--libraries/luajit-2.0/doc/ext_ffi_semantics.html1146
1 files changed, 1146 insertions, 0 deletions
diff --git a/libraries/luajit-2.0/doc/ext_ffi_semantics.html b/libraries/luajit-2.0/doc/ext_ffi_semantics.html
new file mode 100644
index 0000000..661b0b4
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_ffi_semantics.html
@@ -0,0 +1,1146 @@
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 Semantics</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.convtable { line-height: 1.2; }
13tr.convhead td { font-weight: bold; }
14td.convin { width: 11em; }
15td.convop { font-style: italic; width: 16em; }
16</style>
17</head>
18<body>
19<div id="site">
20<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
21</div>
22<div id="head">
23<h1>FFI Semantics</h1>
24</div>
25<div id="nav">
26<ul><li>
27<a href="luajit.html">LuaJIT</a>
28<ul><li>
29<a href="install.html">Installation</a>
30</li><li>
31<a href="running.html">Running</a>
32</li></ul>
33</li><li>
34<a href="extensions.html">Extensions</a>
35<ul><li>
36<a href="ext_ffi.html">FFI Library</a>
37<ul><li>
38<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
39</li><li>
40<a href="ext_ffi_api.html">ffi.* API</a>
41</li><li>
42<a class="current" href="ext_ffi_semantics.html">FFI Semantics</a>
43</li></ul>
44</li><li>
45<a href="ext_jit.html">jit.* Library</a>
46</li><li>
47<a href="ext_c_api.html">Lua/C API</a>
48</li></ul>
49</li><li>
50<a href="status.html">Status</a>
51<ul><li>
52<a href="changes.html">Changes</a>
53</li></ul>
54</li><li>
55<a href="faq.html">FAQ</a>
56</li><li>
57<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
58</li><li>
59<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
60</li></ul>
61</div>
62<div id="main">
63<p>
64This page describes the detailed semantics underlying the FFI library
65and its interaction with both Lua and C&nbsp;code.
66</p>
67<p>
68Given that the FFI library is designed to interface with C&nbsp;code
69and that declarations can be written in plain C&nbsp;syntax, <b>it
70closely follows the C&nbsp;language semantics</b>, wherever possible.
71Some minor concessions are needed for smoother interoperation with Lua
72language semantics.
73</p>
74<p>
75Please don't be overwhelmed by the contents of this page &mdash; this
76is a reference and you may need to consult it, if in doubt. It doesn't
77hurt to skim this page, but most of the semantics "just work" as you'd
78expect them to work. It should be straightforward to write
79applications using the LuaJIT FFI for developers with a C or C++
80background.
81</p>
82<p class="indent" style="color: #c00000;">
83Please note: this doesn't comprise the final specification for the FFI
84semantics, yet. Some semantics may need to be changed, based on your
85feedback. Please <a href="contact.html">report</a> any problems you may
86encounter or any improvements you'd like to see &mdash; thank you!
87</p>
88
89<h2 id="clang">C Language Support</h2>
90<p>
91The FFI library has a built-in C&nbsp;parser with a minimal memory
92footprint. It's used by the <a href="ext_ffi_api.html">ffi.* library
93functions</a> to declare C&nbsp;types or external symbols.
94</p>
95<p>
96It's only purpose is to parse C&nbsp;declarations, as found e.g. in
97C&nbsp;header files. Although it does evaluate constant expressions,
98it's <em>not</em> a C&nbsp;compiler. The body of <tt>inline</tt>
99C&nbsp;function definitions is simply ignored.
100</p>
101<p>
102Also, this is <em>not</em> a validating C&nbsp;parser. It expects and
103accepts correctly formed C&nbsp;declarations, but it may choose to
104ignore bad declarations or show rather generic error messages. If in
105doubt, please check the input against your favorite C&nbsp;compiler.
106</p>
107<p>
108The C&nbsp;parser complies to the <b>C99 language standard</b> plus
109the following extensions:
110</p>
111<ul>
112
113<li>The <tt>'\e'</tt> escape in character and string literals.</li>
114
115<li>The C99/C++ boolean type, declared with the keywords <tt>bool</tt>
116or <tt>_Bool</tt>.</li>
117
118<li>Complex numbers, declared with the keywords <tt>complex</tt> or
119<tt>_Complex</tt>.</li>
120
121<li>Two complex number types: <tt>complex</tt> (aka
122<tt>complex&nbsp;double</tt>) and <tt>complex&nbsp;float</tt>.</li>
123
124<li>Vector types, declared with the GCC <tt>mode</tt> or
125<tt>vector_size</tt> attribute.</li>
126
127<li>Unnamed ('transparent') <tt>struct</tt>/<tt>union</tt> fields
128inside a <tt>struct</tt>/<tt>union</tt>.</li>
129
130<li>Incomplete <tt>enum</tt> declarations, handled like incomplete
131<tt>struct</tt> declarations.</li>
132
133<li>Unnamed <tt>enum</tt> fields inside a
134<tt>struct</tt>/<tt>union</tt>. This is similar to a scoped C++
135<tt>enum</tt>, except that declared constants are visible in the
136global namespace, too.</li>
137
138<li>Scoped <tt>static&nbsp;const</tt> declarations inside a
139<tt>struct</tt>/<tt>union</tt> (from C++).</li>
140
141<li>Zero-length arrays (<tt>[0]</tt>), empty
142<tt>struct</tt>/<tt>union</tt>, variable-length arrays (VLA,
143<tt>[?]</tt>) and variable-length structs (VLS, with a trailing
144VLA).</li>
145
146<li>C++ reference types (<tt>int&nbsp;&amp;x</tt>).</li>
147
148<li>Alternate GCC keywords with '<tt>__</tt>', e.g.
149<tt>__const__</tt>.</li>
150
151<li>GCC <tt>__attribute__</tt> with the following attributes:
152<tt>aligned</tt>, <tt>packed</tt>, <tt>mode</tt>,
153<tt>vector_size</tt>, <tt>cdecl</tt>, <tt>fastcall</tt>,
154<tt>stdcall</tt>.</li>
155
156<li>The GCC <tt>__extension__</tt> keyword and the GCC
157<tt>__alignof__</tt> operator.</li>
158
159<li>GCC <tt>__asm__("symname")</tt> symbol name redirection for
160function declarations.</li>
161
162<li>MSVC keywords for fixed-length types: <tt>__int8</tt>,
163<tt>__int16</tt>, <tt>__int32</tt> and <tt>__int64</tt>.</li>
164
165<li>MSVC <tt>__cdecl</tt>, <tt>__fastcall</tt>, <tt>__stdcall</tt>,
166<tt>__ptr32</tt>, <tt>__ptr64</tt>, <tt>__declspec(align(n))</tt>
167and <tt>#pragma&nbsp;pack</tt>.</li>
168
169<li>All other GCC/MSVC-specific attributes are ignored.</li>
170
171</ul>
172<p>
173The following C&nbsp;types are pre-defined by the C&nbsp;parser (like
174a <tt>typedef</tt>, except re-declarations will be ignored):
175</p>
176<ul>
177
178<li>Vararg handling: <tt>va_list</tt>, <tt>__builtin_va_list</tt>,
179<tt>__gnuc_va_list</tt>.</li>
180
181<li>From <tt>&lt;stddef.h&gt;</tt>: <tt>ptrdiff_t</tt>,
182<tt>size_t</tt>, <tt>wchar_t</tt>.</li>
183
184<li>From <tt>&lt;stdint.h&gt;</tt>: <tt>int8_t</tt>, <tt>int16_t</tt>,
185<tt>int32_t</tt>, <tt>int64_t</tt>, <tt>uint8_t</tt>,
186<tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>,
187<tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li>
188
189</ul>
190<p>
191You're encouraged to use these types in preference to the
192compiler-specific extensions or the target-dependent standard types.
193E.g. <tt>char</tt> differs in signedness and <tt>long</tt> differs in
194size, depending on the target architecture and platform ABI.
195</p>
196<p>
197The following C&nbsp;features are <b>not</b> supported:
198</p>
199<ul>
200
201<li>A declaration must always have a type specifier; it doesn't
202default to an <tt>int</tt> type.</li>
203
204<li>Old-style empty function declarations (K&amp;R) are not allowed.
205All C&nbsp;functions must have a proper prototype declaration. A
206function declared without parameters (<tt>int&nbsp;foo();</tt>) is
207treated as a function taking zero arguments, like in C++.</li>
208
209<li>The <tt>long double</tt> C&nbsp;type is parsed correctly, but
210there's no support for the related conversions, accesses or arithmetic
211operations.</li>
212
213<li>Wide character strings and character literals are not
214supported.</li>
215
216<li><a href="#status">See below</a> for features that are currently
217not implemented.</li>
218
219</ul>
220
221<h2 id="convert">C Type Conversion Rules</h2>
222
223<h3 id="convert_tolua">Conversions from C&nbsp;types to Lua objects</h3>
224<p>
225These conversion rules apply for <em>read accesses</em> to
226C&nbsp;types: indexing pointers, arrays or
227<tt>struct</tt>/<tt>union</tt> types; reading external variables or
228constant values; retrieving return values from C&nbsp;calls:
229</p>
230<table class="convtable">
231<tr class="convhead">
232<td class="convin">Input</td>
233<td class="convop">Conversion</td>
234<td class="convout">Output</td>
235</tr>
236<tr class="odd separate">
237<td class="convin"><tt>int8_t</tt>, <tt>int16_t</tt></td><td class="convop">&rarr;<sup>sign-ext</sup> <tt>int32_t</tt> &rarr; <tt>double</tt></td><td class="convout">number</td></tr>
238<tr class="even">
239<td class="convin"><tt>uint8_t</tt>, <tt>uint16_t</tt></td><td class="convop">&rarr;<sup>zero-ext</sup> <tt>int32_t</tt> &rarr; <tt>double</tt></td><td class="convout">number</td></tr>
240<tr class="odd">
241<td class="convin"><tt>int32_t</tt>, <tt>uint32_t</tt></td><td class="convop">&rarr; <tt>double</tt></td><td class="convout">number</td></tr>
242<tr class="even">
243<td class="convin"><tt>int64_t</tt>, <tt>uint64_t</tt></td><td class="convop">boxed value</td><td class="convout">64 bit int cdata</td></tr>
244<tr class="odd separate">
245<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr; <tt>double</tt></td><td class="convout">number</td></tr>
246<tr class="even separate">
247<td class="convin"><tt>bool</tt></td><td class="convop">0 &rarr; <tt>false</tt>, otherwise <tt>true</tt></td><td class="convout">boolean</td></tr>
248<tr class="odd separate">
249<td class="convin">Complex number</td><td class="convop">boxed value</td><td class="convout">complex cdata</td></tr>
250<tr class="even">
251<td class="convin">Vector</td><td class="convop">boxed value</td><td class="convout">vector cdata</td></tr>
252<tr class="odd">
253<td class="convin">Pointer</td><td class="convop">boxed value</td><td class="convout">pointer cdata</td></tr>
254<tr class="even separate">
255<td class="convin">Array</td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr>
256<tr class="odd">
257<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr>
258</table>
259<p>
260Bitfields or <tt>enum</tt> types are treated like their underlying
261type.
262</p>
263<p>
264Reference types are dereferenced <em>before</em> a conversion can take
265place &mdash; the conversion is applied to the C&nbsp;type pointed to
266by the reference.
267</p>
268
269<h3 id="convert_fromlua">Conversions from Lua objects to C&nbsp;types</h3>
270<p>
271These conversion rules apply for <em>write accesses</em> to
272C&nbsp;types: indexing pointers, arrays or
273<tt>struct</tt>/<tt>union</tt> types; initializing cdata objects;
274casts to C&nbsp;types; writing to external variables; passing
275arguments to C&nbsp;calls:
276</p>
277<table class="convtable">
278<tr class="convhead">
279<td class="convin">Input</td>
280<td class="convop">Conversion</td>
281<td class="convout">Output</td>
282</tr>
283<tr class="odd separate">
284<td class="convin">number</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
285<tr class="even">
286<td class="convin">boolean</td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout"><tt>bool</tt></td></tr>
287<tr class="odd separate">
288<td class="convin">nil</td><td class="convop"><tt>NULL</tt> &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
289<tr class="even">
290<td class="convin">userdata</td><td class="convop">userdata payload &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
291<tr class="odd">
292<td class="convin">lightuserdata</td><td class="convop">lightuserdata address &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
293<tr class="even separate">
294<td class="convin">string</td><td class="convop">match against <tt>enum</tt> constant</td><td class="convout"><tt>enum</tt></td></tr>
295<tr class="odd">
296<td class="convin">string</td><td class="convop">copy string data + zero-byte</td><td class="convout"><tt>int8_t[]</tt>, <tt>uint8_t[]</tt></td></tr>
297<tr class="even">
298<td class="convin">string</td><td class="convop">string data &rarr;</td><td class="convout"><tt>const char[]</tt></td></tr>
299<tr class="odd separate">
300<td class="convin">function</td><td class="convop"><a href="#callback">create callback</a> &rarr;</td><td class="convout">C function type</td></tr>
301<tr class="even separate">
302<td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout">Array</td></tr>
303<tr class="odd">
304<td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr>
305<tr class="even separate">
306<td class="convin">cdata</td><td class="convop">cdata payload &rarr;</td><td class="convout">C type</td></tr>
307</table>
308<p>
309If the result type of this conversion doesn't match the
310C&nbsp;type of the destination, the
311<a href="#convert_between">conversion rules between C&nbsp;types</a>
312are applied.
313</p>
314<p>
315Reference types are immutable after initialization ("no re-seating of
316references"). For initialization purposes or when passing values to
317reference parameters, they are treated like pointers. Note that unlike
318in C++, there's no way to implement automatic reference generation of
319variables under the Lua language semantics. If you want to call a
320function with a reference parameter, you need to explicitly pass a
321one-element array.
322</p>
323
324<h3 id="convert_between">Conversions between C&nbsp;types</h3>
325<p>
326These conversion rules are more or less the same as the standard
327C&nbsp;conversion rules. Some rules only apply to casts, or require
328pointer or type compatibility:
329</p>
330<table class="convtable">
331<tr class="convhead">
332<td class="convin">Input</td>
333<td class="convop">Conversion</td>
334<td class="convout">Output</td>
335</tr>
336<tr class="odd separate">
337<td class="convin">Signed integer</td><td class="convop">&rarr;<sup>narrow or sign-extend</sup></td><td class="convout">Integer</td></tr>
338<tr class="even">
339<td class="convin">Unsigned integer</td><td class="convop">&rarr;<sup>narrow or zero-extend</sup></td><td class="convout">Integer</td></tr>
340<tr class="odd">
341<td class="convin">Integer</td><td class="convop">&rarr;<sup>round</sup></td><td class="convout"><tt>double</tt>, <tt>float</tt></td></tr>
342<tr class="even">
343<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>trunc</sup> <tt>int32_t</tt> &rarr;<sup>narrow</sup></td><td class="convout"><tt>(u)int8_t</tt>, <tt>(u)int16_t</tt></td></tr>
344<tr class="odd">
345<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>trunc</sup></td><td class="convout"><tt>(u)int32_t</tt>, <tt>(u)int64_t</tt></td></tr>
346<tr class="even">
347<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>round</sup></td><td class="convout"><tt>float</tt>, <tt>double</tt></td></tr>
348<tr class="odd separate">
349<td class="convin">Number</td><td class="convop">n == 0 &rarr; 0, otherwise 1</td><td class="convout"><tt>bool</tt></td></tr>
350<tr class="even">
351<td class="convin"><tt>bool</tt></td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout">Number</td></tr>
352<tr class="odd separate">
353<td class="convin">Complex number</td><td class="convop">convert real part</td><td class="convout">Number</td></tr>
354<tr class="even">
355<td class="convin">Number</td><td class="convop">convert real part, imag = 0</td><td class="convout">Complex number</td></tr>
356<tr class="odd">
357<td class="convin">Complex number</td><td class="convop">convert real and imag part</td><td class="convout">Complex number</td></tr>
358<tr class="even separate">
359<td class="convin">Number</td><td class="convop">convert scalar and replicate</td><td class="convout">Vector</td></tr>
360<tr class="odd">
361<td class="convin">Vector</td><td class="convop">copy (same size)</td><td class="convout">Vector</td></tr>
362<tr class="even separate">
363<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr>
364<tr class="odd">
365<td class="convin">Array</td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr>
366<tr class="even">
367<td class="convin">Function</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr>
368<tr class="odd separate">
369<td class="convin">Number</td><td class="convop">convert via <tt>uintptr_t</tt> (cast)</td><td class="convout">Pointer</td></tr>
370<tr class="even">
371<td class="convin">Pointer</td><td class="convop">convert address (compat/cast)</td><td class="convout">Pointer</td></tr>
372<tr class="odd">
373<td class="convin">Pointer</td><td class="convop">convert address (cast)</td><td class="convout">Integer</td></tr>
374<tr class="even">
375<td class="convin">Array</td><td class="convop">convert base address (cast)</td><td class="convout">Integer</td></tr>
376<tr class="odd separate">
377<td class="convin">Array</td><td class="convop">copy (compat)</td><td class="convout">Array</td></tr>
378<tr class="even">
379<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">copy (identical type)</td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr>
380</table>
381<p>
382Bitfields or <tt>enum</tt> types are treated like their underlying
383type.
384</p>
385<p>
386Conversions not listed above will raise an error. E.g. it's not
387possible to convert a pointer to a complex number or vice versa.
388</p>
389
390<h3 id="convert_vararg">Conversions for vararg C&nbsp;function arguments</h3>
391<p>
392The following default conversion rules apply when passing Lua objects
393to the variable argument part of vararg C&nbsp;functions:
394</p>
395<table class="convtable">
396<tr class="convhead">
397<td class="convin">Input</td>
398<td class="convop">Conversion</td>
399<td class="convout">Output</td>
400</tr>
401<tr class="odd separate">
402<td class="convin">number</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
403<tr class="even">
404<td class="convin">boolean</td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout"><tt>bool</tt></td></tr>
405<tr class="odd separate">
406<td class="convin">nil</td><td class="convop"><tt>NULL</tt> &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
407<tr class="even">
408<td class="convin">userdata</td><td class="convop">userdata payload &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
409<tr class="odd">
410<td class="convin">lightuserdata</td><td class="convop">lightuserdata address &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
411<tr class="even separate">
412<td class="convin">string</td><td class="convop">string data &rarr;</td><td class="convout"><tt>const char *</tt></td></tr>
413<tr class="odd separate">
414<td class="convin"><tt>float</tt> cdata</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
415<tr class="even">
416<td class="convin">Array cdata</td><td class="convop">take base address</td><td class="convout">Element pointer</td></tr>
417<tr class="odd">
418<td class="convin"><tt>struct</tt>/<tt>union</tt> cdata</td><td class="convop">take base address</td><td class="convout"><tt>struct</tt>/<tt>union</tt> pointer</td></tr>
419<tr class="even">
420<td class="convin">Function cdata</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr>
421<tr class="odd">
422<td class="convin">Any other cdata</td><td class="convop">no conversion</td><td class="convout">C type</td></tr>
423</table>
424<p>
425To pass a Lua object, other than a cdata object, as a specific type,
426you need to override the conversion rules: create a temporary cdata
427object with a constructor or a cast and initialize it with the value
428to pass:
429</p>
430<p>
431Assuming <tt>x</tt> is a Lua number, here's how to pass it as an
432integer to a vararg function:
433</p>
434<pre class="code">
435ffi.cdef[[
436int printf(const char *fmt, ...);
437]]
438ffi.C.printf("integer value: %d\n", ffi.new("int", x))
439</pre>
440<p>
441If you don't do this, the default Lua number &rarr; <tt>double</tt>
442conversion rule applies. A vararg C&nbsp;function expecting an integer
443will see a garbled or uninitialized value.
444</p>
445
446<h2 id="init">Initializers</h2>
447<p>
448Creating a cdata object with
449<a href="ext_ffi_api.html#ffi_new"><tt>ffi.new()</tt></a> or the
450equivalent constructor syntax always initializes its contents, too.
451Different rules apply, depending on the number of optional
452initializers and the C&nbsp;types involved:
453</p>
454<ul>
455<li>If no initializers are given, the object is filled with zero bytes.</li>
456
457<li>Scalar types (numbers and pointers) accept a single initializer.
458The Lua object is <a href="#convert_fromlua">converted to the scalar
459C&nbsp;type</a>.</li>
460
461<li>Valarrays (complex numbers and vectors) are treated like scalars
462when a single initializer is given. Otherwise they are treated like
463regular arrays.</li>
464
465<li>Aggregate types (arrays and structs) accept either a single
466<a href="#init_table">table initializer</a> or a flat list of
467initializers.</li>
468
469<li>The elements of an array are initialized, starting at index zero.
470If a single initializer is given for an array, it's repeated for all
471remaining elements. This doesn't happen if two or more initializers
472are given: all remaining uninitialized elements are filled with zero
473bytes.</li>
474
475<li>Byte arrays may also be initialized with a Lua string. This copies
476the whole string plus a terminating zero-byte. The copy stops early only
477if the array has a known, fixed size.</li>
478
479<li>The fields of a <tt>struct</tt> are initialized in the order of
480their declaration. Uninitialized fields are filled with zero
481bytes.</li>
482
483<li>Only the first field of a <tt>union</tt> can be initialized with a
484flat initializer.</li>
485
486<li>Elements or fields which are aggregates themselves are initialized
487with a <em>single</em> initializer, but this may be a table
488initializer or a compatible aggregate.</li>
489
490<li>Excess initializers cause an error.</li>
491
492</ul>
493
494<h2 id="init_table">Table Initializers</h2>
495<p>
496The following rules apply if a Lua table is used to initialize an
497Array or a <tt>struct</tt>/<tt>union</tt>:
498</p>
499<ul>
500
501<li>If the table index <tt>[0]</tt> is non-<tt>nil</tt>, then the
502table is assumed to be zero-based. Otherwise it's assumed to be
503one-based.</li>
504
505<li>Array elements, starting at index zero, are initialized one-by-one
506with the consecutive table elements, starting at either index
507<tt>[0]</tt> or <tt>[1]</tt>. This process stops at the first
508<tt>nil</tt> table element.</li>
509
510<li>If exactly one array element was initialized, it's repeated for
511all the remaining elements. Otherwise all remaining uninitialized
512elements are filled with zero bytes.</li>
513
514<li>The above logic only applies to arrays with a known fixed size.
515A VLA is only initialized with the element(s) given in the table.
516Depending on the use case, you may need to explicitly add a
517<tt>NULL</tt> or <tt>0</tt> terminator to a VLA.</li>
518
519<li>If the table has a non-empty hash part, a
520<tt>struct</tt>/<tt>union</tt> is initialized by looking up each field
521name (as a string key) in the table. Each non-<tt>nil</tt> value is
522used to initialize the corresponding field.</li>
523
524<li>Otherwise a <tt>struct</tt>/<tt>union</tt> is initialized in the
525order of the declaration of its fields. Each field is initialized with
526the consecutive table elements, starting at either index <tt>[0]</tt>
527or <tt>[1]</tt>. This process stops at the first <tt>nil</tt> table
528element.</li>
529
530<li>Uninitialized fields of a <tt>struct</tt> are filled with zero
531bytes, except for the trailing VLA of a VLS.</li>
532
533<li>Initialization of a <tt>union</tt> stops after one field has been
534initialized. If no field has been initialized, the <tt>union</tt> is
535filled with zero bytes.</li>
536
537<li>Elements or fields which are aggregates themselves are initialized
538with a <em>single</em> initializer, but this may be a nested table
539initializer (or a compatible aggregate).</li>
540
541<li>Excess initializers for an array cause an error. Excess
542initializers for a <tt>struct</tt>/<tt>union</tt> are ignored.
543Unrelated table entries are ignored, too.</li>
544
545</ul>
546<p>
547Example:
548</p>
549<pre class="code">
550local ffi = require("ffi")
551
552ffi.cdef[[
553struct foo { int a, b; };
554union bar { int i; double d; };
555struct nested { int x; struct foo y; };
556]]
557
558ffi.new("int[3]", {}) --> 0, 0, 0
559ffi.new("int[3]", {1}) --> 1, 1, 1
560ffi.new("int[3]", {1,2}) --> 1, 2, 0
561ffi.new("int[3]", {1,2,3}) --> 1, 2, 3
562ffi.new("int[3]", {[0]=1}) --> 1, 1, 1
563ffi.new("int[3]", {[0]=1,2}) --> 1, 2, 0
564ffi.new("int[3]", {[0]=1,2,3}) --> 1, 2, 3
565ffi.new("int[3]", {[0]=1,2,3,4}) --> error: too many initializers
566
567ffi.new("struct foo", {}) --> a = 0, b = 0
568ffi.new("struct foo", {1}) --> a = 1, b = 0
569ffi.new("struct foo", {1,2}) --> a = 1, b = 2
570ffi.new("struct foo", {[0]=1,2}) --> a = 1, b = 2
571ffi.new("struct foo", {b=2}) --> a = 0, b = 2
572ffi.new("struct foo", {a=1,b=2,c=3}) --> a = 1, b = 2 'c' is ignored
573
574ffi.new("union bar", {}) --> i = 0, d = 0.0
575ffi.new("union bar", {1}) --> i = 1, d = ?
576ffi.new("union bar", {[0]=1,2}) --> i = 1, d = ? '2' is ignored
577ffi.new("union bar", {d=2}) --> i = ?, d = 2.0
578
579ffi.new("struct nested", {1,{2,3}}) --> x = 1, y.a = 2, y.b = 3
580ffi.new("struct nested", {x=1,y={2,3}}) --> x = 1, y.a = 2, y.b = 3
581</pre>
582
583<h2 id="cdata_ops">Operations on cdata Objects</h2>
584<p>
585All of the standard Lua operators can be applied to cdata objects or a
586mix of a cdata object and another Lua object. The following list shows
587the valid combinations. All other combinations currently raise an
588error.
589</p>
590<p>
591Reference types are dereferenced <em>before</em> performing each of
592the operations below &mdash; the operation is applied to the
593C&nbsp;type pointed to by the reference.
594</p>
595<p>
596The pre-defined operations are always tried first before deferring to a
597metamethod for a ctype (if defined).
598</p>
599
600<h3 id="cdata_array">Indexing a cdata object</h3>
601<ul>
602
603<li><b>Indexing a pointer/array</b>: a cdata pointer/array can be
604indexed by a cdata number or a Lua number. The element address is
605computed as the base address plus the number value multiplied by the
606element size in bytes. A read access loads the element value and
607<a href="#convert_tolua">converts it to a Lua object</a>. A write
608access <a href="#convert_fromlua">converts a Lua object to the element
609type</a> and stores the converted value to the element. An error is
610raised if the element size is undefined or a write access to a
611constant element is attempted.</li>
612
613<li><b>Dereferencing a <tt>struct</tt>/<tt>union</tt> field</b>: a
614cdata <tt>struct</tt>/<tt>union</tt> or a pointer to a
615<tt>struct</tt>/<tt>union</tt> can be dereferenced by a string key,
616giving the field name. The field address is computed as the base
617address plus the relative offset of the field. A read access loads the
618field value and <a href="#convert_tolua">converts it to a Lua
619object</a>. A write access <a href="#convert_fromlua">converts a Lua
620object to the field type</a> and stores the converted value to the
621field. An error is raised if a write access to a constant
622<tt>struct</tt>/<tt>union</tt> or a constant field is attempted.</li>
623
624<li><b>Indexing a complex number</b>: a complex number can be indexed
625either by a cdata number or a Lua number with the values 0 or 1, or by
626the strings <tt>"re"</tt> or <tt>"im"</tt>. A read access loads the
627real part (<tt>[0]</tt>, <tt>.re</tt>) or the imaginary part
628(<tt>[1]</tt>, <tt>.im</tt>) part of a complex number and
629<a href="#convert_tolua">converts it to a Lua number</a>. The
630sub-parts of a complex number are immutable &mdash; assigning to an
631index of a complex number raises an error. Accessing out-of-bound
632indexes returns unspecified results, but is guaranteed not to trigger
633memory access violations.</li>
634
635<li><b>Indexing a vector</b>: a vector is treated like an array for
636indexing purposes, except the vector elements are immutable &mdash;
637assigning to an index of a vector raises an error.</li>
638
639</ul>
640<p>
641Note: since there's (deliberately) no address-of operator, a cdata
642object holding a value type is effectively immutable after
643initialization. The JIT compiler benefits from this fact when applying
644certain optimizations.
645</p>
646<p>
647As a consequence of this, the <em>elements</em> of complex numbers and
648vectors are immutable. But the elements of an aggregate holding these
649types <em>may</em> be modified of course. I.e. you cannot assign to
650<tt>foo.c.im</tt>, but you can assign a (newly created) complex number
651to <tt>foo.c</tt>.
652</p>
653
654<h3 id="cdata_call">Calling a cdata object</h3>
655<ul>
656
657<li><b>Constructor</b>: a ctype object can be called and used as a
658<a href="ext_ffi_api.html#ffi_new">constructor</a>.</li>
659
660<li><b>C&nbsp;function call</b>: a cdata function or cdata function
661pointer can be called. The passed arguments are
662<a href="#convert_fromlua">converted to the C&nbsp;types</a> of the
663parameters given by the function declaration. Arguments passed to the
664variable argument part of vararg C&nbsp;function use
665<a href="#convert_vararg">special conversion rules</a>. This
666C&nbsp;function is called and the return value (if any) is
667<a href="#convert_tolua">converted to a Lua object</a>.<br>
668On Windows/x86 systems, <tt>__stdcall</tt> functions are automatically
669detected and a function declared as <tt>__cdecl</tt> (the default) is
670silently fixed up after the first call.</li>
671
672</ul>
673
674<h3 id="cdata_arith">Arithmetic on cdata objects</h3>
675<ul>
676
677<li><b>Pointer arithmetic</b>: a cdata pointer/array and a cdata
678number or a Lua number can be added or subtracted. The number must be
679on the right hand side for a subtraction. The result is a pointer of
680the same type with an address plus or minus the number value
681multiplied by the element size in bytes. An error is raised if the
682element size is undefined.</li>
683
684<li><b>Pointer difference</b>: two compatible cdata pointers/arrays
685can be subtracted. The result is the difference between their
686addresses, divided by the element size in bytes. An error is raised if
687the element size is undefined or zero.</li>
688
689<li><b>64&nbsp;bit integer arithmetic</b>: the standard arithmetic
690operators (<tt>+&nbsp;-&nbsp;*&nbsp;/&nbsp;%&nbsp;^</tt> and unary
691minus) can be applied to two cdata numbers, or a cdata number and a
692Lua number. If one of them is an <tt>uint64_t</tt>, the other side is
693converted to an <tt>uint64_t</tt> and an unsigned arithmetic operation
694is performed. Otherwise both sides are converted to an
695<tt>int64_t</tt> and a signed arithmetic operation is performed. The
696result is a boxed 64&nbsp;bit cdata object.<br>
697
698These rules ensure that 64&nbsp;bit integers are "sticky". Any
699expression involving at least one 64&nbsp;bit integer operand results
700in another one. The undefined cases for the division, modulo and power
701operators return <tt>2LL&nbsp;^&nbsp;63</tt> or
702<tt>2ULL&nbsp;^&nbsp;63</tt>.<br>
703
704You'll have to explicitly convert a 64&nbsp;bit integer to a Lua
705number (e.g. for regular floating-point calculations) with
706<tt>tonumber()</tt>. But note this may incur a precision loss.</li>
707
708</ul>
709
710<h3 id="cdata_comp">Comparisons of cdata objects</h3>
711<ul>
712
713<li><b>Pointer comparison</b>: two compatible cdata pointers/arrays
714can be compared. The result is the same as an unsigned comparison of
715their addresses. <tt>nil</tt> is treated like a <tt>NULL</tt> pointer,
716which is compatible with any other pointer type.</li>
717
718<li><b>64&nbsp;bit integer comparison</b>: two cdata numbers, or a
719cdata number and a Lua number can be compared with each other. If one
720of them is an <tt>uint64_t</tt>, the other side is converted to an
721<tt>uint64_t</tt> and an unsigned comparison is performed. Otherwise
722both sides are converted to an <tt>int64_t</tt> and a signed
723comparison is performed.</li>
724
725</ul>
726
727<h3 id="cdata_key">cdata objects as table keys</h3>
728<p>
729Lua tables may be indexed by cdata objects, but this doesn't provide
730any useful semantics &mdash; <b>cdata objects are unsuitable as table
731keys!</b>
732</p>
733<p>
734A cdata object is treated like any other garbage-collected object and
735is hashed and compared by its address for table indexing. Since
736there's no interning for cdata value types, the same value may be
737boxed in different cdata objects with different addresses. Thus
738<tt>t[1LL+1LL]</tt> and <tt>t[2LL]</tt> usually <b>do not</b> point to
739the same hash slot and they certainly <b>do not</b> point to the same
740hash slot as <tt>t[2]</tt>.
741</p>
742<p>
743It would seriously drive up implementation complexity and slow down
744the common case, if one were to add extra handling for by-value
745hashing and comparisons to Lua tables. Given the ubiquity of their use
746inside the VM, this is not acceptable.
747</p>
748<p>
749There are three viable alternatives, if you really need to use cdata
750objects as keys:
751</p>
752<ul>
753
754<li>If you can get by with the precision of Lua numbers
755(52&nbsp;bits), then use <tt>tonumber()</tt> on a cdata number or
756combine multiple fields of a cdata aggregate to a Lua number. Then use
757the resulting Lua number as a key when indexing tables.<br>
758One obvious benefit: <tt>t[tonumber(2LL)]</tt> <b>does</b> point to
759the same slot as <tt>t[2]</tt>.</li>
760
761<li>Otherwise use either <tt>tostring()</tt> on 64&nbsp;bit integers
762or complex numbers or combine multiple fields of a cdata aggregate to
763a Lua string (e.g. with
764<a href="ext_ffi_api.html#ffi_string"><tt>ffi.string()</tt></a>). Then
765use the resulting Lua string as a key when indexing tables.</li>
766
767<li>Create your own specialized hash table implementation using the
768C&nbsp;types provided by the FFI library, just like you would in
769C&nbsp;code. Ultimately this may give much better performance than the
770other alternatives or what a generic by-value hash table could
771possibly provide.</li>
772
773</ul>
774
775<h2 id="gc">Garbage Collection of cdata Objects</h2>
776<p>
777All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or
778implicitly (accessors) created cdata objects are garbage collected.
779You need to ensure to retain valid references to cdata objects
780somewhere on a Lua stack, an upvalue or in a Lua table while they are
781still in use. Once the last reference to a cdata object is gone, the
782garbage collector will automatically free the memory used by it (at
783the end of the next GC cycle).
784</p>
785<p>
786Please note that pointers themselves are cdata objects, however they
787are <b>not</b> followed by the garbage collector. So e.g. if you
788assign a cdata array to a pointer, you must keep the cdata object
789holding the array alive as long as the pointer is still in use:
790</p>
791<pre class="code">
792ffi.cdef[[
793typedef struct { int *a; } foo_t;
794]]
795
796local s = ffi.new("foo_t", ffi.new("int[10]")) -- <span style="color:#c00000;">WRONG!</span>
797
798local a = ffi.new("int[10]") -- <span style="color:#00a000;">OK</span>
799local s = ffi.new("foo_t", a)
800-- Now do something with 's', but keep 'a' alive until you're done.
801</pre>
802<p>
803Similar rules apply for Lua strings which are implicitly converted to
804<tt>"const&nbsp;char&nbsp;*"</tt>: the string object itself must be
805referenced somewhere or it'll be garbage collected eventually. The
806pointer will then point to stale data, which may have already been
807overwritten. Note that <em>string literals</em> are automatically kept
808alive as long as the function containing it (actually its prototype)
809is not garbage collected.
810</p>
811<p>
812Objects which are passed as an argument to an external C&nbsp;function
813are kept alive until the call returns. So it's generally safe to
814create temporary cdata objects in argument lists. This is a common
815idiom for <a href="#convert_vararg">passing specific C&nbsp;types to
816vararg functions</a>.
817</p>
818<p>
819Memory areas returned by C functions (e.g. from <tt>malloc()</tt>)
820must be manually managed, of course (or use
821<a href="ext_ffi_api.html#ffi_gc"><tt>ffi.gc()</tt></a>). Pointers to
822cdata objects are indistinguishable from pointers returned by C
823functions (which is one of the reasons why the GC cannot follow them).
824</p>
825
826<h2 id="callback">Callbacks</h2>
827<p>
828The LuaJIT FFI automatically generates special callback functions
829whenever a Lua function is converted to a C&nbsp;function pointer. This
830associates the generated callback function pointer with the C&nbsp;type
831of the function pointer and the Lua function object (closure).
832</p>
833<p>
834This can happen implicitly due to the usual conversions, e.g. when
835passing a Lua function to a function pointer argument. Or you can use
836<tt>ffi.cast()</tt> to explicitly cast a Lua function to a
837C&nbsp;function pointer.
838</p>
839<p>
840Currently only certain C&nbsp;function types can be used as callback
841functions. Neither C&nbsp;vararg functions nor functions with
842pass-by-value aggregate argument or result types are supported. There
843are no restrictions for the kind of Lua functions that can be called
844from the callback &mdash; no checks for the proper number of arguments
845are made. The return value of the Lua function will be converted to the
846result type and an error will be thrown for invalid conversions.
847</p>
848<p>
849It's allowed to throw errors across a callback invocation, but it's not
850advisable in general. Do this only if you know the C&nbsp;function, that
851called the callback, copes with the forced stack unwinding and doesn't
852leak resources.
853</p>
854
855<h3 id="callback_resources">Callback resource handling</h3>
856<p>
857Callbacks take up resources &mdash; you can only have a limited number
858of them at the same time (500&nbsp;-&nbsp;1000, depending on the
859architecture). The associated Lua functions are anchored to prevent
860garbage collection, too.
861</p>
862<p>
863<b>Callbacks due to implicit conversions are permanent!</b> There is no
864way to guess their lifetime, since the C&nbsp;side might store the
865function pointer for later use (typical for GUI toolkits). The associated
866resources cannot be reclaimed until termination:
867</p>
868<pre class="code">
869ffi.cdef[[
870typedef int (__stdcall *WNDENUMPROC)(void *hwnd, intptr_t l);
871int EnumWindows(WNDENUMPROC func, intptr_t l);
872]]
873
874-- Implicit conversion to a callback via function pointer argument.
875local count = 0
876ffi.C.EnumWindows(function(hwnd, l)
877 count = count + 1
878 return true
879end, 0)
880-- The callback is permanent and its resources cannot be reclaimed!
881-- Ok, so this may not be a problem, if you do this only once.
882</pre>
883<p>
884Note: this example shows that you <em>must</em> properly declare
885<tt>__stdcall</tt> callbacks on Windows/x86 systems. The calling
886convention cannot be automatically detected, unlike for
887<tt>__stdcall</tt> calls <em>to</em> Windows functions.
888</p>
889<p>
890For some use cases it's necessary to free up the resources or to
891dynamically redirect callbacks. Use an explicit cast to a
892C&nbsp;function pointer and keep the resulting cdata object. Then use
893the <a href="ext_ffi_api.html#callback_free"><tt>cb:free()</tt></a>
894or <a href="ext_ffi_api.html#callback_set"><tt>cb:set()</tt></a> methods
895on the cdata object:
896</p>
897<pre class="code">
898-- Explicitly convert to a callback via cast.
899local count = 0
900local cb = ffi.cast("WNDENUMPROC", function(hwnd, l)
901 count = count + 1
902 return true
903end)
904
905-- Pass it to a C function.
906ffi.C.EnumWindows(cb, 0)
907-- EnumWindows doesn't need the callback after it returns, so free it.
908
909cb:free()
910-- The callback function pointer is no longer valid and its resources
911-- will be reclaimed. The created Lua closure will be garbage collected.
912</pre>
913
914<h3 id="callback_performance">Callback performance</h3>
915<p>
916<b>Callbacks are slow!</b> First, the C&nbsp;to Lua transition itself
917has an unavoidable cost, similar to a <tt>lua_call()</tt> or
918<tt>lua_pcall()</tt>. Argument and result marshalling add to that cost.
919And finally, neither the C&nbsp;compiler nor LuaJIT can inline or
920optimize across the language barrier and hoist repeated computations out
921of a callback function.
922</p>
923<p>
924Do not use callbacks for performance-sensitive work: e.g. consider a
925numerical integration routine which takes a user-defined function to
926integrate over. It's a bad idea to call a user-defined Lua function from
927C&nbsp;code millions of times. The callback overhead will be absolutely
928detrimental for performance.
929</p>
930<p>
931It's considerably faster to write the numerical integration routine
932itself in Lua &mdash; the JIT compiler will be able to inline the
933user-defined function and optimize it together with its calling context,
934with very competitive performance.
935</p>
936<p>
937As a general guideline: <b>use callbacks only when you must</b>, because
938of existing C&nbsp;APIs. E.g. callback performance is irrelevant for a
939GUI application, which waits for user input most of the time, anyway.
940</p>
941<p>
942For new designs <b>avoid push-style APIs</b> (C&nbsp;function repeatedly
943calling a callback for each result). Instead <b>use pull-style APIs</b>
944(call a C&nbsp;function repeatedly to get a new result). Calls from Lua
945to C via the FFI are much faster than the other way round. Most well-designed
946libraries already use pull-style APIs (read/write, get/put).
947</p>
948
949<h2 id="clib">C Library Namespaces</h2>
950<p>
951A C&nbsp;library namespace is a special kind of object which allows
952access to the symbols contained in shared libraries or the default
953symbol namespace. The default
954<a href="ext_ffi_api.html#ffi_C"><tt>ffi.C</tt></a> namespace is
955automatically created when the FFI library is loaded. C&nbsp;library
956namespaces for specific shared libraries may be created with the
957<a href="ext_ffi_api.html#ffi_load"><tt>ffi.load()</tt></a> API
958function.
959</p>
960<p>
961Indexing a C&nbsp;library namespace object with a symbol name (a Lua
962string) automatically binds it to the library. First the symbol type
963is resolved &mdash; it must have been declared with
964<a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a>. Then the
965symbol address is resolved by searching for the symbol name in the
966associated shared libraries or the default symbol namespace. Finally,
967the resulting binding between the symbol name, the symbol type and its
968address is cached. Missing symbol declarations or nonexistent symbol
969names cause an error.
970</p>
971<p>
972This is what happens on a <b>read access</b> for the different kinds of
973symbols:
974</p>
975<ul>
976
977<li>External functions: a cdata object with the type of the function
978and its address is returned.</li>
979
980<li>External variables: the symbol address is dereferenced and the
981loaded value is <a href="#convert_tolua">converted to a Lua object</a>
982and returned.</li>
983
984<li>Constant values (<tt>static&nbsp;const</tt> or <tt>enum</tt>
985constants): the constant is <a href="#convert_tolua">converted to a
986Lua object</a> and returned.</li>
987
988</ul>
989<p>
990This is what happens on a <b>write access</b>:
991</p>
992<ul>
993
994<li>External variables: the value to be written is
995<a href="#convert_fromlua">converted to the C&nbsp;type</a> of the
996variable and then stored at the symbol address.</li>
997
998<li>Writing to constant variables or to any other symbol type causes
999an error, like any other attempted write to a constant location.</li>
1000
1001</ul>
1002<p>
1003C&nbsp;library namespaces themselves are garbage collected objects. If
1004the last reference to the namespace object is gone, the garbage
1005collector will eventually release the shared library reference and
1006remove all memory associated with the namespace. Since this may
1007trigger the removal of the shared library from the memory of the
1008running process, it's generally <em>not safe</em> to use function
1009cdata objects obtained from a library if the namespace object may be
1010unreferenced.
1011</p>
1012<p>
1013Performance notice: the JIT compiler specializes to the identity of
1014namespace objects and to the strings used to index it. This
1015effectively turns function cdata objects into constants. It's not
1016useful and actually counter-productive to explicitly cache these
1017function objects, e.g. <tt>local strlen = ffi.C.strlen</tt>. OTOH it
1018<em>is</em> useful to cache the namespace itself, e.g. <tt>local C =
1019ffi.C</tt>.
1020</p>
1021
1022<h2 id="policy">No Hand-holding!</h2>
1023<p>
1024The FFI library has been designed as <b>a low-level library</b>. The
1025goal is to interface with C&nbsp;code and C&nbsp;data types with a
1026minimum of overhead. This means <b>you can do anything you can do
1027from&nbsp;C</b>: access all memory, overwrite anything in memory, call
1028machine code at any memory address and so on.
1029</p>
1030<p>
1031The FFI library provides <b>no memory safety</b>, unlike regular Lua
1032code. It will happily allow you to dereference a <tt>NULL</tt>
1033pointer, to access arrays out of bounds or to misdeclare
1034C&nbsp;functions. If you make a mistake, your application might crash,
1035just like equivalent C&nbsp;code would.
1036</p>
1037<p>
1038This behavior is inevitable, since the goal is to provide full
1039interoperability with C&nbsp;code. Adding extra safety measures, like
1040bounds checks, would be futile. There's no way to detect
1041misdeclarations of C&nbsp;functions, since shared libraries only
1042provide symbol names, but no type information. Likewise there's no way
1043to infer the valid range of indexes for a returned pointer.
1044</p>
1045<p>
1046Again: the FFI library is a low-level library. This implies it needs
1047to be used with care, but it's flexibility and performance often
1048outweigh this concern. If you're a C or C++ developer, it'll be easy
1049to apply your existing knowledge. OTOH writing code for the FFI
1050library is not for the faint of heart and probably shouldn't be the
1051first exercise for someone with little experience in Lua, C or C++.
1052</p>
1053<p>
1054As a corollary of the above, the FFI library is <b>not safe for use by
1055untrusted Lua code</b>. If you're sandboxing untrusted Lua code, you
1056definitely don't want to give this code access to the FFI library or
1057to <em>any</em> cdata object (except 64&nbsp;bit integers or complex
1058numbers). Any properly engineered Lua sandbox needs to provide safety
1059wrappers for many of the standard Lua library functions &mdash;
1060similar wrappers need to be written for high-level operations on FFI
1061data types, too.
1062</p>
1063
1064<h2 id="status">Current Status</h2>
1065<p>
1066The initial release of the FFI library has some limitations and is
1067missing some features. Most of these will be fixed in future releases.
1068</p>
1069<p>
1070<a href="#clang">C language support</a> is
1071currently incomplete:
1072</p>
1073<ul>
1074<li>C&nbsp;declarations are not passed through a C&nbsp;pre-processor,
1075yet.</li>
1076<li>The C&nbsp;parser is able to evaluate most constant expressions
1077commonly found in C&nbsp;header files. However it doesn't handle the
1078full range of C&nbsp;expression semantics and may fail for some
1079obscure constructs.</li>
1080<li><tt>static const</tt> declarations only work for integer types
1081up to 32&nbsp;bits. Neither declaring string constants nor
1082floating-point constants is supported.</li>
1083<li>Packed <tt>struct</tt> bitfields that cross container boundaries
1084are not implemented.</li>
1085<li>Native vector types may be defined with the GCC <tt>mode</tt> or
1086<tt>vector_size</tt> attribute. But no operations other than loading,
1087storing and initializing them are supported, yet.</li>
1088<li>The <tt>volatile</tt> type qualifier is currently ignored by
1089compiled code.</li>
1090<li><a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> silently
1091ignores all re-declarations.</li>
1092</ul>
1093<p>
1094The JIT compiler already handles a large subset of all FFI operations.
1095It automatically falls back to the interpreter for unimplemented
1096operations (you can check for this with the
1097<a href="running.html#opt_j"><tt>-jv</tt></a> command line option).
1098The following operations are currently not compiled and may exhibit
1099suboptimal performance, especially when used in inner loops:
1100</p>
1101<ul>
1102<li>Array/<tt>struct</tt> copies and bulk initializations.</li>
1103<li>Bitfield accesses and initializations.</li>
1104<li>Vector operations.</li>
1105<li>Table initializers.</li>
1106<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li>
1107<li>Allocations of variable-length arrays or structs.</li>
1108<li>Allocations of C&nbsp;types with a size &gt; 64&nbsp;bytes or an
1109alignment &gt; 8&nbsp;bytes.</li>
1110<li>Conversions from lightuserdata to <tt>void&nbsp;*</tt>.</li>
1111<li>Pointer differences for element sizes that are not a power of
1112two.</li>
1113<li>Calls to C&nbsp;functions with aggregates passed or returned by
1114value.</li>
1115<li>Calls to ctype metamethods which are not plain functions.</li>
1116<li>ctype <tt>__newindex</tt> tables and non-string lookups in ctype
1117<tt>__index</tt> tables.</li>
1118<li><tt>tostring()</tt> for cdata types.</li>
1119<li>Calls to the following <a href="ext_ffi_api.html">ffi.* API</a>
1120functions: <tt>cdef</tt>, <tt>load</tt>, <tt>typeof</tt>,
1121<tt>metatype</tt>, <tt>gc</tt>, <tt>sizeof</tt>, <tt>alignof</tt>,
1122<tt>offsetof</tt>.</li>
1123</ul>
1124<p>
1125Other missing features:
1126</p>
1127<ul>
1128<li>Bit operations for 64&nbsp;bit types.</li>
1129<li>Arithmetic for <tt>complex</tt> numbers.</li>
1130<li>Passing structs by value to vararg C&nbsp;functions.</li>
1131<li><a href="extensions.html#exceptions">C++ exception interoperability</a>
1132does not extend to C&nbsp;functions called via the FFI, if the call is
1133compiled.</li>
1134</ul>
1135<br class="flush">
1136</div>
1137<div id="foot">
1138<hr class="hide">
1139Copyright &copy; 2005-2011 Mike Pall
1140<span class="noprint">
1141&middot;
1142<a href="contact.html">Contact</a>
1143</span>
1144</div>
1145</body>
1146</html>
generated by cgit v1.1 at 2025-01-13 21:16:32 +0000