ffi.* API Functions

+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.
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 init arguments provide optional initializers. The created +cdata object is filled with zero bytes if no initializers are given. +Scalar types accept a single initializer. Aggregates can either be +initialized with a flat list of initializers or a single aggregate +initializer (see the C type +conversion rules). Excess initializers cause an error. +

+If a single initializer is given for an array, it's repeated for all +remaining elements. This doesn't happen if two or more initializers +are given — all uninitialized elements are filled with zero +bytes. The fields of a struct are initialized in the order of +their declaration. Uninitialized fields are filled with zero bytes. +Only the first field of union can be initialized with a flat +initializer. Elements or fields which are aggregates themselves are +initialized with a single init argument, but this +may be an aggregate initializer of course. +

+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 +rules or to convert pointers to addresses or vice versa. For maximum +portability you should convert a pointer to its address as follows: +

+local addr = tonumber(ffi.cast("intptr_t", ptr))
+

+ +

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. +

+ +

Utility Functions

+ +

`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. +In case src is a Lua string, the maximum copy length is the +number of bytes of the string plus a zero-terminator. Caveat: the +copied data may not be zero-terminated if len ≤ #src. +

+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. +

+Performance notice: ffi.copy() may be used as a faster +(inlineable) 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 +(inlineable) 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). Otherwise returns +false. 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. +

+
+