-This page describes the API functions provided by the FFI library in -detail. It's recommended to read through the -introduction and the -FFI tutorial first. -
- -Glossary
--
-
- cdecl — An abstract C type declaration (a Lua -string). -
- ctype — A C type object. This is a special kind of -cdata returned by ffi.typeof(). It serves as a -cdata constructor when called. -
- cdata — A C data object. It holds a value of the -corresponding ctype. -
- ct — A C type specification which can be used for -most of the API functions. Either a cdecl, a ctype or a -cdata serving as a template type. -
- cb — A callback object. This is a C data object -holding a special function pointer. Calling this function from -C code runs an associated Lua function. -
- VLA — A variable-length array is declared with a -? instead of the number of elements, e.g. "int[?]". -The number of elements (nelem) must be given when it's -created. -
- VLS — A variable-length struct is a struct C -type where the last element is a VLA. The same rules for -declaration and creation apply. -
Declaring and Accessing External Symbols
--External symbols must be declared first and can then be accessed by -indexing a C library -namespace, which automatically binds the symbol to a specific -library. -
- -ffi.cdef(def)
--Adds multiple C declarations for types or external symbols (named -variables or functions). def must be a Lua string. It's -recommended to use the syntactic sugar for string arguments as -follows: -
-
-ffi.cdef[[
-typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef.
-int dofoo(foo_t *f, int n); /* Declare an external C function. */
-]]
-
--The contents of the string (the part in green above) must be a -sequence of -C declarations, -separated by semicolons. The trailing semicolon for a single -declaration may be omitted. -
--Please note that external symbols are only declared, but they -are not bound to any specific address, yet. Binding is -achieved with C library namespaces (see below). -
--C declarations are not passed through a C pre-processor, -yet. No pre-processor tokens are allowed, except for -#pragma pack. Replace #define in existing -C header files with enum, static const -or typedef and/or pass the files through an external -C pre-processor (once). Be careful not to include unneeded or -redundant declarations from unrelated header files. -
- -ffi.C
--This is the default C library namespace — note the -uppercase 'C'. It binds to the default set of symbols or -libraries on the target system. These are more or less the same as a -C compiler would offer by default, without specifying extra link -libraries. -
--On POSIX systems, this binds to symbols in the default or global -namespace. This includes all exported symbols from the executable and -any libraries loaded into the global namespace. This includes at least -libc, libm, libdl (on Linux), -libgcc (if compiled with GCC), as well as any exported -symbols from the Lua/C API provided by LuaJIT itself. -
--On Windows systems, this binds to symbols exported from the -*.exe, the lua51.dll (i.e. the Lua/C API -provided by LuaJIT itself), the C runtime library LuaJIT was linked -with (msvcrt*.dll), kernel32.dll, -user32.dll and gdi32.dll. -
- -clib = ffi.load(name [,global])
--This loads the dynamic library given by name and returns -a new C library namespace which binds to its symbols. On POSIX -systems, if global is true, the library symbols are -loaded into the global namespace, too. -
--If name is a path, the library is loaded from this path. -Otherwise name is canonicalized in a system-dependent way and -searched in the default search path for dynamic libraries: -
--On POSIX systems, if the name contains no dot, the extension -.so is appended. Also, the lib prefix is prepended -if necessary. So ffi.load("z") looks for "libz.so" -in the default shared library search path. -
--On Windows systems, if the name contains no dot, the extension -.dll is appended. So ffi.load("ws2_32") looks for -"ws2_32.dll" in the default DLL search path. -
- -Creating cdata Objects
--The following API functions create cdata objects (type() -returns "cdata"). All created cdata objects are -garbage collected. -
- -cdata = ffi.new(ct [,nelem] [,init...])
-cdata = ctype([nelem,] [init...])
--Creates a cdata object for the given ct. VLA/VLS types -require the nelem argument. The second syntax uses a ctype as -a constructor and is otherwise fully equivalent. -
--The cdata object is initialized according to the -rules for initializers, -using the optional init arguments. Excess initializers cause -an error. -
--Performance notice: if you want to create many objects of one kind, -parse the cdecl only once and get its ctype with -ffi.typeof(). Then use the ctype as a constructor repeatedly. -
--Please note that an anonymous struct declaration implicitly -creates a new and distinguished ctype every time you use it for -ffi.new(). This is probably not what you want, -especially if you create more than one cdata object. Different anonymous -structs are not considered assignment-compatible by the -C standard, even though they may have the same fields! Also, they -are considered different types by the JIT-compiler, which may cause an -excessive number of traces. It's strongly suggested to either declare -a named struct or typedef with ffi.cdef() -or to create a single ctype object for an anonymous struct -with ffi.typeof(). -
- -ctype = ffi.typeof(ct)
--Creates a ctype object for the given ct. -
--This function is especially useful to parse a cdecl only once and then -use the resulting ctype object as a constructor. -
- -cdata = ffi.cast(ct, init)
--Creates a scalar cdata object for the given ct. The cdata -object is initialized with init using the "cast" variant of -the C type conversion -rules. -
--This functions is mainly useful to override the pointer compatibility -checks or to convert pointers to addresses or vice versa. -
- -ctype = ffi.metatype(ct, metatable)
--Creates a ctype object for the given ct and associates it with -a metatable. Only struct/union types, complex numbers -and vectors are allowed. Other types may be wrapped in a -struct, if needed. -
--The association with a metatable is permanent and cannot be changed -afterwards. Neither the contents of the metatable nor the -contents of an __index table (if any) may be modified -afterwards. The associated metatable automatically applies to all uses -of this type, no matter how the objects are created or where they -originate from. Note that pre-defined operations on types have -precedence (e.g. declared field names cannot be overriden). -
--All standard Lua metamethods are implemented. These are called directly, -without shortcuts and on any mix of types. For binary operations, the -left operand is checked first for a valid ctype metamethod. The -__gc metamethod only applies to struct/union -types and performs an implicit ffi.gc() -call during creation of an instance. -
- -cdata = ffi.gc(cdata, finalizer)
--Associates a finalizer with a pointer or aggregate cdata object. The -cdata object is returned unchanged. -
--This function allows safe integration of unmanaged resources into the -automatic memory management of the LuaJIT garbage collector. Typical -usage: -
--local p = ffi.gc(ffi.C.malloc(n), ffi.C.free) -... -p = nil -- Last reference to p is gone. --- GC will eventually run finalizer: ffi.C.free(p) --
-A cdata finalizer works like the __gc metamethod for userdata -objects: when the last reference to a cdata object is gone, the -associated finalizer is called with the cdata object as an argument. The -finalizer can be a Lua function or a cdata function or cdata function -pointer. An existing finalizer can be removed by setting a nil -finalizer, e.g. right before explicitly deleting a resource: -
--ffi.C.free(ffi.gc(p, nil)) -- Manually free the memory. -- -
C Type Information
--The following API functions return information about C types. -They are most useful for inspecting cdata objects. -
- -size = ffi.sizeof(ct [,nelem])
--Returns the size of ct in bytes. Returns nil if -the size is not known (e.g. for "void" or function types). -Requires nelem for VLA/VLS types, except for cdata objects. -
- -align = ffi.alignof(ct)
--Returns the minimum required alignment for ct in bytes. -
- -ofs [,bpos,bsize] = ffi.offsetof(ct, field)
--Returns the offset (in bytes) of field relative to the start -of ct, which must be a struct. Additionally returns -the position and the field size (in bits) for bit fields. -
- -status = ffi.istype(ct, obj)
--Returns true if obj has the C type given by -ct. Returns false otherwise. -
--C type qualifiers (const etc.) are ignored. Pointers are -checked with the standard pointer compatibility rules, but without any -special treatment for void *. If ct specifies a -struct/union, then a pointer to this type is accepted, -too. Otherwise the types must match exactly. -
--Note: this function accepts all kinds of Lua objects for the -obj argument, but always returns false for non-cdata -objects. -
- -Utility Functions
- -err = ffi.errno([newerr])
--Returns the error number set by the last C function call which -indicated an error condition. If the optional newerr argument -is present, the error number is set to the new value and the previous -value is returned. -
--This function offers a portable and OS-independent way to get and set the -error number. Note that only some C functions set the error -number. And it's only significant if the function actually indicated an -error condition (e.g. with a return value of -1 or -NULL). Otherwise, it may or may not contain any previously set -value. -
--You're advised to call this function only when needed and as close as -possible after the return of the related C function. The -errno value is preserved across hooks, memory allocations, -invocations of the JIT compiler and other internal VM activity. The same -applies to the value returned by GetLastError() on Windows, but -you need to declare and call it yourself. -
- -str = ffi.string(ptr [,len])
--Creates an interned Lua string from the data pointed to by -ptr. -
--If the optional argument len is missing, ptr is -converted to a "char *" and the data is assumed to be -zero-terminated. The length of the string is computed with -strlen(). -
--Otherwise ptr is converted to a "void *" and -len gives the length of the data. The data may contain -embedded zeros and need not be byte-oriented (though this may cause -endianess issues). -
--This function is mainly useful to convert (temporary) -"const char *" pointers returned by -C functions to Lua strings and store them or pass them to other -functions expecting a Lua string. The Lua string is an (interned) copy -of the data and bears no relation to the original data area anymore. -Lua strings are 8 bit clean and may be used to hold arbitrary, -non-character data. -
--Performance notice: it's faster to pass the length of the string, if -it's known. E.g. when the length is returned by a C call like -sprintf(). -
- -ffi.copy(dst, src, len)
-ffi.copy(dst, str)
--Copies the data pointed to by src to dst. -dst is converted to a "void *" and src -is converted to a "const void *". -
--In the first syntax, len gives the number of bytes to copy. -Caveat: if src is a Lua string, then len must not -exceed #src+1. -
--In the second syntax, the source of the copy must be a Lua string. All -bytes of the string plus a zero-terminator are copied to -dst (i.e. #src+1 bytes). -
--Performance notice: ffi.copy() may be used as a faster -(inlinable) replacement for the C library functions -memcpy(), strcpy() and strncpy(). -
- -ffi.fill(dst, len [,c])
--Fills the data pointed to by dst with len constant -bytes, given by c. If c is omitted, the data is -zero-filled. -
--Performance notice: ffi.fill() may be used as a faster -(inlinable) replacement for the C library function -memset(dst, c, len). Please note the different -order of arguments! -
- -Target-specific Information
- -status = ffi.abi(param)
--Returns true if param (a Lua string) applies for the -target ABI (Application Binary Interface). Returns false -otherwise. The following parameters are currently defined: -
-| Parameter | -Description | -
| 32bit | 32 bit architecture |
| 64bit | 64 bit architecture |
| le | Little-endian architecture |
| be | Big-endian architecture |
| fpu | Target has a hardware FPU |
| softfp | softfp calling conventions |
| hardfp | hardfp calling conventions |
| eabi | EABI variant of the standard ABI |
| win | Windows variant of the standard ABI |
ffi.os
--Contains the target OS name. Same contents as -jit.os. -
- -ffi.arch
--Contains the target architecture name. Same contents as -jit.arch. -
- -Methods for Callbacks
--The C types for callbacks -have some extra methods: -
- -cb:free()
--Free the resources associated with a callback. The associated Lua -function is unanchored and may be garbage collected. The callback -function pointer is no longer valid and must not be called anymore -(it may be reused by a subsequently created callback). -
- -cb:set(func)
--Associate a new Lua function with a callback. The C type of the -callback and the callback function pointer are unchanged. -
--This method is useful to dynamically switch the receiver of callbacks -without creating a new callback each time and registering it again (e.g. -with a GUI library). -
- -Extended Standard Library Functions
--The following standard library functions have been extended to work -with cdata objects: -
- -n = tonumber(cdata)
--Converts a number cdata object to a double and returns it as -a Lua number. This is particularly useful for boxed 64 bit -integer values. Caveat: this conversion may incur a precision loss. -
- -s = tostring(cdata)
--Returns a string representation of the value of 64 bit integers -("nnnLL" or "nnnULL") or -complex numbers ("re±imi"). Otherwise -returns a string representation of the C type of a ctype object -("ctype<type>") or a cdata object -("cdata<type>: address"). -
- -Extensions to the Lua Parser
--The parser for Lua source code treats numeric literals with the -suffixes LL or ULL as signed or unsigned 64 bit -integers. Case doesn't matter, but uppercase is recommended for -readability. It handles both decimal (42LL) and hexadecimal -(0x2aLL) literals. -
--The imaginary part of complex numbers can be specified by suffixing -number literals with i or I, e.g. 12.5i. -Caveat: you'll need to use 1i to get an imaginary part with -the value one, since i itself still refers to a variable -named i. -
--