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