luna - luajit/doc/ext_ffi

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