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