Mercurial
comparison third_party/luajit/doc/ext_ffi_api.html @ 186:8cf4ec5e2191 hg-web
Fixed merge conflict.
| author | MrJuneJune <me@mrjunejune.com> |
|---|---|
| date | Fri, 23 Jan 2026 22:38:59 -0800 |
| parents | 94705b5986b3 |
| children |
comparison
equal
deleted
inserted
replaced
| 176:fed99fc04e12 | 186:8cf4ec5e2191 |
|---|---|
| 1 <!DOCTYPE html> | |
| 2 <html> | |
| 3 <head> | |
| 4 <title>ffi.* API Functions</title> | |
| 5 <meta charset="utf-8"> | |
| 6 <meta name="Copyright" content="Copyright (C) 2005-2023"> | |
| 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"> | |
| 11 table.abitable { width: 30em; line-height: 1.2; } | |
| 12 tr.abihead td { font-weight: bold; } | |
| 13 td.abiparam { font-weight: bold; width: 6em; } | |
| 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><tt>ffi.*</tt> API Functions</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">»</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 class="current" href="ext_ffi_api.html">ffi.* API</a> | |
| 41 </li><li> | |
| 42 <a 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">»</span></a> | |
| 55 </li><li> | |
| 56 <a href="https://luajit.org/faq.html">FAQ <span class="ext">»</span></a> | |
| 57 </li><li> | |
| 58 <a href="https://luajit.org/list.html">Mailing List <span class="ext">»</span></a> | |
| 59 </li></ul> | |
| 60 </div> | |
| 61 <div id="main"> | |
| 62 <p> | |
| 63 This page describes the API functions provided by the FFI library in | |
| 64 detail. It's recommended to read through the | |
| 65 <a href="ext_ffi.html">introduction</a> and the | |
| 66 <a href="ext_ffi_tutorial.html">FFI tutorial</a> first. | |
| 67 </p> | |
| 68 | |
| 69 <h2 id="glossary">Glossary</h2> | |
| 70 <ul> | |
| 71 <li><b>cdecl</b> — An abstract C type declaration (a Lua | |
| 72 string).</li> | |
| 73 <li><b>ctype</b> — A C type object. This is a special kind of | |
| 74 <b>cdata</b> returned by <tt>ffi.typeof()</tt>. It serves as a | |
| 75 <b>cdata</b> <a href="#ffi_new">constructor</a> when called.</li> | |
| 76 <li><b>cdata</b> — A C data object. It holds a value of the | |
| 77 corresponding <b>ctype</b>.</li> | |
| 78 <li><b>ct</b> — A C type specification which can be used for | |
| 79 most of the API functions. Either a <b>cdecl</b>, a <b>ctype</b> or a | |
| 80 <b>cdata</b> serving as a template type.</li> | |
| 81 <li><b>cb</b> — A callback object. This is a C data object | |
| 82 holding a special function pointer. Calling this function from | |
| 83 C code runs an associated Lua function.</li> | |
| 84 <li><b>VLA</b> — A variable-length array is declared with a | |
| 85 <tt>?</tt> instead of the number of elements, e.g. <tt>"int[?]"</tt>. | |
| 86 The number of elements (<tt>nelem</tt>) must be given when it's | |
| 87 <a href="#ffi_new">created</a>.</li> | |
| 88 <li><b>VLS</b> — A variable-length struct is a <tt>struct</tt> C | |
| 89 type where the last element is a <b>VLA</b>. The same rules for | |
| 90 declaration and creation apply.</li> | |
| 91 </ul> | |
| 92 | |
| 93 <h2 id="decl">Declaring and Accessing External Symbols</h2> | |
| 94 <p> | |
| 95 External symbols must be declared first and can then be accessed by | |
| 96 indexing a <a href="ext_ffi_semantics.html#clib">C library | |
| 97 namespace</a>, which automatically binds the symbol to a specific | |
| 98 library. | |
| 99 </p> | |
| 100 | |
| 101 <h3 id="ffi_cdef"><tt>ffi.cdef(def)</tt></h3> | |
| 102 <p> | |
| 103 Adds multiple C declarations for types or external symbols (named | |
| 104 variables or functions). <tt>def</tt> must be a Lua string. It's | |
| 105 recommended to use the syntactic sugar for string arguments as | |
| 106 follows: | |
| 107 </p> | |
| 108 <pre class="code"> | |
| 109 ffi.cdef[[ | |
| 110 <span style="color:#00a000;">typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef. | |
| 111 int dofoo(foo_t *f, int n); /* Declare an external C function. */</span> | |
| 112 ]] | |
| 113 </pre> | |
| 114 <p> | |
| 115 The contents of the string (the part in green above) must be a | |
| 116 sequence of | |
| 117 <a href="ext_ffi_semantics.html#clang">C declarations</a>, | |
| 118 separated by semicolons. The trailing semicolon for a single | |
| 119 declaration may be omitted. | |
| 120 </p> | |
| 121 <p> | |
| 122 Please note, that external symbols are only <em>declared</em>, but they | |
| 123 are <em>not bound</em> to any specific address, yet. Binding is | |
| 124 achieved with C library namespaces (see below). | |
| 125 </p> | |
| 126 <p style="color: #c00000;"> | |
| 127 C declarations are not passed through a C pre-processor, | |
| 128 yet. No pre-processor tokens are allowed, except for | |
| 129 <tt>#pragma pack</tt>. Replace <tt>#define</tt> in existing | |
| 130 C header files with <tt>enum</tt>, <tt>static const</tt> | |
| 131 or <tt>typedef</tt> and/or pass the files through an external | |
| 132 C pre-processor (once). Be careful not to include unneeded or | |
| 133 redundant declarations from unrelated header files. | |
| 134 </p> | |
| 135 | |
| 136 <h3 id="ffi_C"><tt>ffi.C</tt></h3> | |
| 137 <p> | |
| 138 This is the default C library namespace — note the | |
| 139 uppercase <tt>'C'</tt>. It binds to the default set of symbols or | |
| 140 libraries on the target system. These are more or less the same as a | |
| 141 C compiler would offer by default, without specifying extra link | |
| 142 libraries. | |
| 143 </p> | |
| 144 <p> | |
| 145 On POSIX systems, this binds to symbols in the default or global | |
| 146 namespace. This includes all exported symbols from the executable and | |
| 147 any libraries loaded into the global namespace. This includes at least | |
| 148 <tt>libc</tt>, <tt>libm</tt>, <tt>libdl</tt> (on Linux), | |
| 149 <tt>libgcc</tt> (if compiled with GCC), as well as any exported | |
| 150 symbols from the Lua/C API provided by LuaJIT itself. | |
| 151 </p> | |
| 152 <p> | |
| 153 On Windows systems, this binds to symbols exported from the | |
| 154 <tt>*.exe</tt>, the <tt>lua51.dll</tt> (i.e. the Lua/C API | |
| 155 provided by LuaJIT itself), the C runtime library LuaJIT was linked | |
| 156 with (<tt>msvcrt*.dll</tt>), <tt>kernel32.dll</tt>, | |
| 157 <tt>user32.dll</tt> and <tt>gdi32.dll</tt>. | |
| 158 </p> | |
| 159 | |
| 160 <h3 id="ffi_load"><tt>clib = ffi.load(name [,global])</tt></h3> | |
| 161 <p> | |
| 162 This loads the dynamic library given by <tt>name</tt> and returns | |
| 163 a new C library namespace which binds to its symbols. On POSIX | |
| 164 systems, if <tt>global</tt> is <tt>true</tt>, the library symbols are | |
| 165 loaded into the global namespace, too. | |
| 166 </p> | |
| 167 <p> | |
| 168 If <tt>name</tt> is a path, the library is loaded from this path. | |
| 169 Otherwise <tt>name</tt> is canonicalized in a system-dependent way and | |
| 170 searched in the default search path for dynamic libraries: | |
| 171 </p> | |
| 172 <p> | |
| 173 On POSIX systems, if the name contains no dot, the extension | |
| 174 <tt>.so</tt> is appended. Also, the <tt>lib</tt> prefix is prepended | |
| 175 if necessary. So <tt>ffi.load("z")</tt> looks for <tt>"libz.so"</tt> | |
| 176 in the default shared library search path. | |
| 177 </p> | |
| 178 <p> | |
| 179 On Windows systems, if the name contains no dot, the extension | |
| 180 <tt>.dll</tt> is appended. So <tt>ffi.load("ws2_32")</tt> looks for | |
| 181 <tt>"ws2_32.dll"</tt> in the default DLL search path. | |
| 182 </p> | |
| 183 | |
| 184 <h2 id="create">Creating cdata Objects</h2> | |
| 185 <p> | |
| 186 The following API functions create cdata objects (<tt>type()</tt> | |
| 187 returns <tt>"cdata"</tt>). All created cdata objects are | |
| 188 <a href="ext_ffi_semantics.html#gc">garbage collected</a>. | |
| 189 </p> | |
| 190 | |
| 191 <h3 id="ffi_new"><tt>cdata = ffi.new(ct [,nelem] [,init...])<br> | |
| 192 cdata = <em>ctype</em>([nelem,] [init...])</tt></h3> | |
| 193 <p> | |
| 194 Creates a cdata object for the given <tt>ct</tt>. VLA/VLS types | |
| 195 require the <tt>nelem</tt> argument. The second syntax uses a ctype as | |
| 196 a constructor and is otherwise fully equivalent. | |
| 197 </p> | |
| 198 <p> | |
| 199 The cdata object is initialized according to the | |
| 200 <a href="ext_ffi_semantics.html#init">rules for initializers</a>, | |
| 201 using the optional <tt>init</tt> arguments. Excess initializers cause | |
| 202 an error. | |
| 203 </p> | |
| 204 <p> | |
| 205 Performance notice: if you want to create many objects of one kind, | |
| 206 parse the cdecl only once and get its ctype with | |
| 207 <tt>ffi.typeof()</tt>. Then use the ctype as a constructor repeatedly. | |
| 208 </p> | |
| 209 <p style="font-size: 8pt;"> | |
| 210 Please note, that an anonymous <tt>struct</tt> declaration implicitly | |
| 211 creates a new and distinguished ctype every time you use it for | |
| 212 <tt>ffi.new()</tt>. This is probably <b>not</b> what you want, | |
| 213 especially if you create more than one cdata object. Different anonymous | |
| 214 <tt>structs</tt> are not considered assignment-compatible by the | |
| 215 C standard, even though they may have the same fields! Also, they | |
| 216 are considered different types by the JIT-compiler, which may cause an | |
| 217 excessive number of traces. It's strongly suggested to either declare | |
| 218 a named <tt>struct</tt> or <tt>typedef</tt> with <tt>ffi.cdef()</tt> | |
| 219 or to create a single ctype object for an anonymous <tt>struct</tt> | |
| 220 with <tt>ffi.typeof()</tt>. | |
| 221 </p> | |
| 222 | |
| 223 <h3 id="ffi_typeof"><tt>ctype = ffi.typeof(ct)</tt></h3> | |
| 224 <p> | |
| 225 Creates a ctype object for the given <tt>ct</tt>. | |
| 226 </p> | |
| 227 <p> | |
| 228 This function is especially useful to parse a cdecl only once and then | |
| 229 use the resulting ctype object as a <a href="#ffi_new">constructor</a>. | |
| 230 </p> | |
| 231 | |
| 232 <h3 id="ffi_cast"><tt>cdata = ffi.cast(ct, init)</tt></h3> | |
| 233 <p> | |
| 234 Creates a scalar cdata object for the given <tt>ct</tt>. The cdata | |
| 235 object is initialized with <tt>init</tt> using the "cast" variant of | |
| 236 the <a href="ext_ffi_semantics.html#convert">C type conversion | |
| 237 rules</a>. | |
| 238 </p> | |
| 239 <p> | |
| 240 This functions is mainly useful to override the pointer compatibility | |
| 241 checks or to convert pointers to addresses or vice versa. | |
| 242 </p> | |
| 243 | |
| 244 <h3 id="ffi_metatype"><tt>ctype = ffi.metatype(ct, metatable)</tt></h3> | |
| 245 <p> | |
| 246 Creates a ctype object for the given <tt>ct</tt> and associates it with | |
| 247 a metatable. Only <tt>struct</tt>/<tt>union</tt> types, complex numbers | |
| 248 and vectors are allowed. Other types may be wrapped in a | |
| 249 <tt>struct</tt>, if needed. | |
| 250 </p> | |
| 251 <p> | |
| 252 The association with a metatable is permanent and cannot be changed | |
| 253 afterwards. Neither the contents of the <tt>metatable</tt> nor the | |
| 254 contents of an <tt>__index</tt> table (if any) may be modified | |
| 255 afterwards. The associated metatable automatically applies to all uses | |
| 256 of this type, no matter how the objects are created or where they | |
| 257 originate from. Note that predefined operations on types have | |
| 258 precedence (e.g. declared field names cannot be overridden). | |
| 259 </p> | |
| 260 <p> | |
| 261 All standard Lua metamethods are implemented. These are called directly, | |
| 262 without shortcuts, and on any mix of types. For binary operations, the | |
| 263 left operand is checked first for a valid ctype metamethod. The | |
| 264 <tt>__gc</tt> metamethod only applies to <tt>struct</tt>/<tt>union</tt> | |
| 265 types and performs an implicit <a href="#ffi_gc"><tt>ffi.gc()</tt></a> | |
| 266 call during creation of an instance. | |
| 267 </p> | |
| 268 | |
| 269 <h3 id="ffi_gc"><tt>cdata = ffi.gc(cdata, finalizer)</tt></h3> | |
| 270 <p> | |
| 271 Associates a finalizer with a pointer or aggregate cdata object. The | |
| 272 cdata object is returned unchanged. | |
| 273 </p> | |
| 274 <p> | |
| 275 This function allows safe integration of unmanaged resources into the | |
| 276 automatic memory management of the LuaJIT garbage collector. Typical | |
| 277 usage: | |
| 278 </p> | |
| 279 <pre class="code"> | |
| 280 local p = ffi.gc(ffi.C.malloc(n), ffi.C.free) | |
| 281 ... | |
| 282 p = nil -- Last reference to p is gone. | |
| 283 -- GC will eventually run finalizer: ffi.C.free(p) | |
| 284 </pre> | |
| 285 <p> | |
| 286 A cdata finalizer works like the <tt>__gc</tt> metamethod for userdata | |
| 287 objects: when the last reference to a cdata object is gone, the | |
| 288 associated finalizer is called with the cdata object as an argument. The | |
| 289 finalizer can be a Lua function or a cdata function or cdata function | |
| 290 pointer. An existing finalizer can be removed by setting a <tt>nil</tt> | |
| 291 finalizer, e.g. right before explicitly deleting a resource: | |
| 292 </p> | |
| 293 <pre class="code"> | |
| 294 ffi.C.free(ffi.gc(p, nil)) -- Manually free the memory. | |
| 295 </pre> | |
| 296 | |
| 297 <h2 id="info">C Type Information</h2> | |
| 298 <p> | |
| 299 The following API functions return information about C types. | |
| 300 They are most useful for inspecting cdata objects. | |
| 301 </p> | |
| 302 | |
| 303 <h3 id="ffi_sizeof"><tt>size = ffi.sizeof(ct [,nelem])</tt></h3> | |
| 304 <p> | |
| 305 Returns the size of <tt>ct</tt> in bytes. Returns <tt>nil</tt> if | |
| 306 the size is not known (e.g. for <tt>"void"</tt> or function types). | |
| 307 Requires <tt>nelem</tt> for VLA/VLS types, except for cdata objects. | |
| 308 </p> | |
| 309 | |
| 310 <h3 id="ffi_alignof"><tt>align = ffi.alignof(ct)</tt></h3> | |
| 311 <p> | |
| 312 Returns the minimum required alignment for <tt>ct</tt> in bytes. | |
| 313 </p> | |
| 314 | |
| 315 <h3 id="ffi_offsetof"><tt>ofs [,bpos,bsize] = ffi.offsetof(ct, field)</tt></h3> | |
| 316 <p> | |
| 317 Returns the offset (in bytes) of <tt>field</tt> relative to the start | |
| 318 of <tt>ct</tt>, which must be a <tt>struct</tt>. Additionally returns | |
| 319 the position and the field size (in bits) for bit fields. | |
| 320 </p> | |
| 321 | |
| 322 <h3 id="ffi_istype"><tt>status = ffi.istype(ct, obj)</tt></h3> | |
| 323 <p> | |
| 324 Returns <tt>true</tt> if <tt>obj</tt> has the C type given by | |
| 325 <tt>ct</tt>. Returns <tt>false</tt> otherwise. | |
| 326 </p> | |
| 327 <p> | |
| 328 C type qualifiers (<tt>const</tt> etc.) are ignored. Pointers are | |
| 329 checked with the standard pointer compatibility rules, but without any | |
| 330 special treatment for <tt>void *</tt>. If <tt>ct</tt> specifies a | |
| 331 <tt>struct</tt>/<tt>union</tt>, then a pointer to this type is accepted, | |
| 332 too. Otherwise the types must match exactly. | |
| 333 </p> | |
| 334 <p> | |
| 335 Note: this function accepts all kinds of Lua objects for the | |
| 336 <tt>obj</tt> argument, but always returns <tt>false</tt> for non-cdata | |
| 337 objects. | |
| 338 </p> | |
| 339 | |
| 340 <h2 id="util">Utility Functions</h2> | |
| 341 | |
| 342 <h3 id="ffi_errno"><tt>err = ffi.errno([newerr])</tt></h3> | |
| 343 <p> | |
| 344 Returns the error number set by the last C function call which | |
| 345 indicated an error condition. If the optional <tt>newerr</tt> argument | |
| 346 is present, the error number is set to the new value and the previous | |
| 347 value is returned. | |
| 348 </p> | |
| 349 <p> | |
| 350 This function offers a portable and OS-independent way to get and set the | |
| 351 error number. Note that only <em>some</em> C functions set the error | |
| 352 number. And it's only significant if the function actually indicated an | |
| 353 error condition (e.g. with a return value of <tt>-1</tt> or | |
| 354 <tt>NULL</tt>). Otherwise, it may or may not contain any previously set | |
| 355 value. | |
| 356 </p> | |
| 357 <p> | |
| 358 You're advised to call this function only when needed and as close as | |
| 359 possible after the return of the related C function. The | |
| 360 <tt>errno</tt> value is preserved across hooks, memory allocations, | |
| 361 invocations of the JIT compiler and other internal VM activity. The same | |
| 362 applies to the value returned by <tt>GetLastError()</tt> on Windows, but | |
| 363 you need to declare and call it yourself. | |
| 364 </p> | |
| 365 | |
| 366 <h3 id="ffi_string"><tt>str = ffi.string(ptr [,len])</tt></h3> | |
| 367 <p> | |
| 368 Creates an interned Lua string from the data pointed to by | |
| 369 <tt>ptr</tt>. | |
| 370 </p> | |
| 371 <p> | |
| 372 If the optional argument <tt>len</tt> is missing, <tt>ptr</tt> is | |
| 373 converted to a <tt>"char *"</tt> and the data is assumed to be | |
| 374 zero-terminated. The length of the string is computed with | |
| 375 <tt>strlen()</tt>. | |
| 376 </p> | |
| 377 <p> | |
| 378 Otherwise <tt>ptr</tt> is converted to a <tt>"void *"</tt> and | |
| 379 <tt>len</tt> gives the length of the data. The data may contain | |
| 380 embedded zeros and need not be byte-oriented (though this may cause | |
| 381 endianess issues). | |
| 382 </p> | |
| 383 <p> | |
| 384 This function is mainly useful to convert (temporary) | |
| 385 <tt>"const char *"</tt> pointers returned by | |
| 386 C functions to Lua strings and store them or pass them to other | |
| 387 functions expecting a Lua string. The Lua string is an (interned) copy | |
| 388 of the data and bears no relation to the original data area anymore. | |
| 389 Lua strings are 8 bit clean and may be used to hold arbitrary, | |
| 390 non-character data. | |
| 391 </p> | |
| 392 <p> | |
| 393 Performance notice: it's faster to pass the length of the string, if | |
| 394 it's known. E.g. when the length is returned by a C call like | |
| 395 <tt>sprintf()</tt>. | |
| 396 </p> | |
| 397 | |
| 398 <h3 id="ffi_copy"><tt>ffi.copy(dst, src, len)<br> | |
| 399 ffi.copy(dst, str)</tt></h3> | |
| 400 <p> | |
| 401 Copies the data pointed to by <tt>src</tt> to <tt>dst</tt>. | |
| 402 <tt>dst</tt> is converted to a <tt>"void *"</tt> and <tt>src</tt> | |
| 403 is converted to a <tt>"const void *"</tt>. | |
| 404 </p> | |
| 405 <p> | |
| 406 In the first syntax, <tt>len</tt> gives the number of bytes to copy. | |
| 407 Caveat: if <tt>src</tt> is a Lua string, then <tt>len</tt> must not | |
| 408 exceed <tt>#src+1</tt>. | |
| 409 </p> | |
| 410 <p> | |
| 411 In the second syntax, the source of the copy must be a Lua string. All | |
| 412 bytes of the string <em>plus a zero-terminator</em> are copied to | |
| 413 <tt>dst</tt> (i.e. <tt>#src+1</tt> bytes). | |
| 414 </p> | |
| 415 <p> | |
| 416 Performance notice: <tt>ffi.copy()</tt> may be used as a faster | |
| 417 (inlinable) replacement for the C library functions | |
| 418 <tt>memcpy()</tt>, <tt>strcpy()</tt> and <tt>strncpy()</tt>. | |
| 419 </p> | |
| 420 | |
| 421 <h3 id="ffi_fill"><tt>ffi.fill(dst, len [,c])</tt></h3> | |
| 422 <p> | |
| 423 Fills the data pointed to by <tt>dst</tt> with <tt>len</tt> constant | |
| 424 bytes, given by <tt>c</tt>. If <tt>c</tt> is omitted, the data is | |
| 425 zero-filled. | |
| 426 </p> | |
| 427 <p> | |
| 428 Performance notice: <tt>ffi.fill()</tt> may be used as a faster | |
| 429 (inlinable) replacement for the C library function | |
| 430 <tt>memset(dst, c, len)</tt>. Please note the different | |
| 431 order of arguments! | |
| 432 </p> | |
| 433 | |
| 434 <h2 id="target">Target-specific Information</h2> | |
| 435 | |
| 436 <h3 id="ffi_abi"><tt>status = ffi.abi(param)</tt></h3> | |
| 437 <p> | |
| 438 Returns <tt>true</tt> if <tt>param</tt> (a Lua string) applies for the | |
| 439 target ABI (Application Binary Interface). Returns <tt>false</tt> | |
| 440 otherwise. The following parameters are currently defined: | |
| 441 </p> | |
| 442 <table class="abitable"> | |
| 443 <tr class="abihead"> | |
| 444 <td class="abiparam">Parameter</td> | |
| 445 <td class="abidesc">Description</td> | |
| 446 </tr> | |
| 447 <tr class="odd separate"> | |
| 448 <td class="abiparam">32bit</td><td class="abidesc">32 bit architecture</td></tr> | |
| 449 <tr class="even"> | |
| 450 <td class="abiparam">64bit</td><td class="abidesc">64 bit architecture</td></tr> | |
| 451 <tr class="odd separate"> | |
| 452 <td class="abiparam">le</td><td class="abidesc">Little-endian architecture</td></tr> | |
| 453 <tr class="even"> | |
| 454 <td class="abiparam">be</td><td class="abidesc">Big-endian architecture</td></tr> | |
| 455 <tr class="odd separate"> | |
| 456 <td class="abiparam">fpu</td><td class="abidesc">Target has a hardware FPU</td></tr> | |
| 457 <tr class="even"> | |
| 458 <td class="abiparam">softfp</td><td class="abidesc">softfp calling conventions</td></tr> | |
| 459 <tr class="odd"> | |
| 460 <td class="abiparam">hardfp</td><td class="abidesc">hardfp calling conventions</td></tr> | |
| 461 <tr class="even separate"> | |
| 462 <td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr> | |
| 463 <tr class="odd"> | |
| 464 <td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr> | |
| 465 <tr class="even"> | |
| 466 <td class="abiparam">pauth</td><td class="abidesc">Pointer authentication ABI</td></tr> | |
| 467 <tr class="odd"> | |
| 468 <td class="abiparam">uwp</td><td class="abidesc">Universal Windows Platform</td></tr> | |
| 469 <tr class="even"> | |
| 470 <td class="abiparam">gc64</td><td class="abidesc">64 bit GC references</td></tr> | |
| 471 </table> | |
| 472 | |
| 473 <h3 id="ffi_os"><tt>ffi.os</tt></h3> | |
| 474 <p> | |
| 475 Contains the target OS name. Same contents as | |
| 476 <a href="ext_jit.html#jit_os"><tt>jit.os</tt></a>. | |
| 477 </p> | |
| 478 | |
| 479 <h3 id="ffi_arch"><tt>ffi.arch</tt></h3> | |
| 480 <p> | |
| 481 Contains the target architecture name. Same contents as | |
| 482 <a href="ext_jit.html#jit_arch"><tt>jit.arch</tt></a>. | |
| 483 </p> | |
| 484 | |
| 485 <h2 id="callback">Methods for Callbacks</h2> | |
| 486 <p> | |
| 487 The C types for <a href="ext_ffi_semantics.html#callback">callbacks</a> | |
| 488 have some extra methods: | |
| 489 </p> | |
| 490 | |
| 491 <h3 id="callback_free"><tt>cb:free()</tt></h3> | |
| 492 <p> | |
| 493 Free the resources associated with a callback. The associated Lua | |
| 494 function is unanchored and may be garbage collected. The callback | |
| 495 function pointer is no longer valid and must not be called again | |
| 496 (it may be reused by a subsequently created callback). | |
| 497 </p> | |
| 498 | |
| 499 <h3 id="callback_set"><tt>cb:set(func)</tt></h3> | |
| 500 <p> | |
| 501 Associate a new Lua function with a callback. The C type of the | |
| 502 callback and the callback function pointer are unchanged. | |
| 503 </p> | |
| 504 <p> | |
| 505 This method is useful to dynamically switch the receiver of callbacks | |
| 506 without creating a new callback each time and registering it again (e.g. | |
| 507 with a GUI library). | |
| 508 </p> | |
| 509 | |
| 510 <h2 id="extended">Extended Standard Library Functions</h2> | |
| 511 <p> | |
| 512 The following standard library functions have been extended to work | |
| 513 with cdata objects: | |
| 514 </p> | |
| 515 | |
| 516 <h3 id="tonumber"><tt>n = tonumber(cdata)</tt></h3> | |
| 517 <p> | |
| 518 Converts a number cdata object to a <tt>double</tt> and returns it as | |
| 519 a Lua number. This is particularly useful for boxed 64 bit | |
| 520 integer values. Caveat: this conversion may incur a precision loss. | |
| 521 </p> | |
| 522 | |
| 523 <h3 id="tostring"><tt>s = tostring(cdata)</tt></h3> | |
| 524 <p> | |
| 525 Returns a string representation of the value of 64 bit integers | |
| 526 (<tt><b>"</b>nnn<b>LL"</b></tt> or <tt><b>"</b>nnn<b>ULL"</b></tt>) or | |
| 527 complex numbers (<tt><b>"</b>re±im<b>i"</b></tt>). Otherwise | |
| 528 returns a string representation of the C type of a ctype object | |
| 529 (<tt><b>"ctype<</b>type<b>>"</b></tt>) or a cdata object | |
| 530 (<tt><b>"cdata<</b>type<b>>: </b>address"</tt>), unless you | |
| 531 override it with a <tt>__tostring</tt> metamethod (see | |
| 532 <a href="#ffi_metatype"><tt>ffi.metatype()</tt></a>). | |
| 533 </p> | |
| 534 | |
| 535 <h3 id="pairs"><tt>iter, obj, start = pairs(cdata)<br> | |
| 536 iter, obj, start = ipairs(cdata)<br></tt></h3> | |
| 537 <p> | |
| 538 Calls the <tt>__pairs</tt> or <tt>__ipairs</tt> metamethod of the | |
| 539 corresponding ctype. | |
| 540 </p> | |
| 541 | |
| 542 <h2 id="literals">Extensions to the Lua Parser</h2> | |
| 543 <p> | |
| 544 The parser for Lua source code treats numeric literals with the | |
| 545 suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64 bit | |
| 546 integers. Case doesn't matter, but uppercase is recommended for | |
| 547 readability. It handles decimal (<tt>42LL</tt>), hexadecimal | |
| 548 (<tt>0x2aLL</tt>) and binary (<tt>0b101010LL</tt>) literals. | |
| 549 </p> | |
| 550 <p> | |
| 551 The imaginary part of complex numbers can be specified by suffixing | |
| 552 number literals with <tt>i</tt> or <tt>I</tt>, e.g. <tt>12.5i</tt>. | |
| 553 Caveat: you'll need to use <tt>1i</tt> to get an imaginary part with | |
| 554 the value one, since <tt>i</tt> itself still refers to a variable | |
| 555 named <tt>i</tt>. | |
| 556 </p> | |
| 557 <br class="flush"> | |
| 558 </div> | |
| 559 <div id="foot"> | |
| 560 <hr class="hide"> | |
| 561 Copyright © 2005-2023 | |
| 562 <span class="noprint"> | |
| 563 · | |
| 564 <a href="contact.html">Contact</a> | |
| 565 </span> | |
| 566 </div> | |
| 567 </body> | |
| 568 </html> |