doc/ext_ffi_api.html

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