ffi.cdef
Signature
function ffi.cdef(declarations)Description
CLib returned by ffi.load or of ffi.C. The declarations must match the platform ABI and the real signatures of the library functions they describe.Parameters
declarations- A string containing valid C declarations, each terminated by a semicolon.
Returns
Nothing.
Errors
- Raises an error if
declarationsis not a string. - Raises an error if the declarations cannot be parsed or use a type that is not supported.
Example
import ffi
ffi.cdef(```
typedef struct {
int x;
int y;
} Point;
int abs(int value);
```)
print(ffi.sizeof("Point")) // 8
print(ffi.C.abs(-5)) // 5
ffi.load
Signature
function ffi.load(path, global = false)Description
path and return a CLib object, representing the loaded C library. When global is true, request global symbol visibility. Declared functions are accessed as attributes of the returned object, such as lib.printf. Only functions previously declared with ffi.cdef can be looked up.Parameters
path- The name or path of the shared library to load.
global- (Optional) When
true, request global symbol visibility for the loaded library. Defaults tofalse.
Returns
A CLib object.
Errors
- Raises an error if
pathis not a string. - Raises an error if the shared library cannot be loaded.
Example
import os, ffi
ffi.cdef("int printf(const char* fmt, ...);")
const clib = os.name == "windows" ? ffi.load("msvcrt") : ffi.C
clib.printf("Hello, %s! Number: %d\n", "everybody", 123)ffi.cnew
Signature
function ffi.cnew(ctype, initializer)Description
CData value of the given C type. Without an initializer, the storage is zero-initialized. An optional list initializes the elements of an array, and an optional map initializes the fields of a record. Scalar types accept a single value.Parameters
ctype- A C type declaration, a
CType, or the name of a type registered withffi.cdef, such as"int[10]"or"Point". initializer- (Optional) A list to initialize an array, a map to initialize the fields of a record, or a single value to initialize a scalar.
Returns
A CData object of type ctype.
Errors
- Raises an error if
ctypeis not a valid or known C type. - Raises an error if more than one initializer is given.
- Raises an error if the initializer cannot be converted to the requested type.
Example
import ffi
ffi.cdef(```
typedef struct {
int x;
int y;
const char* name;
} Point;
```)
// Zero-initialized array of ten integers
const numbers = ffi.cnew("int[10]")
numbers[0] = 42
// Array initialized from a list
const values = ffi.cnew("int[3]", [10, 20, 30])
print(values[2]) // 30
// Record initialized from a map
const p = ffi.cnew("Point", { x = 30, y = 40, name = "point" })
print(p.x, p.y, ffi.string(p.name))
// Array of records
const points = ffi.cnew("Point[3]")
points[1].x = 10ffi.cast
Signature
function ffi.cast(ctype, value)Description
value to the given C type and return it as CData. When ctype is a function-pointer type, value may be a Teascript callable, which is wrapped as a C callback that native code can invoke. The callback remains valid for as long as the returned CData is alive, so keep a reference to it while native code may call it.Parameters
ctype- The target C type, as a C type declaration or a
CType. value- The value to convert: a number, string, boolean,
nil,CData, or, for function-pointer types, a Teascript callable.
Returns
A CData object of type ctype.
Errors
- Raises an error if
ctypeis not a valid or known C type. - Raises an error if
valuecannot be converted toctype.
Example
import ffi
// Reinterpret a raw pointer as a char pointer
ffi.cdef("void* malloc(size_t size);")
const buf = ffi.cast("char*", ffi.C.malloc(16))
// Wrap a Teascript function as a C callback
ffi.cdef("typedef int (*Comparator)(const void* a, const void* b);")
function compare(a, b)
{
return ffi.cast("const int*", a)[0] - ffi.cast("const int*", b)[0]
}
const callback = ffi.cast("Comparator", compare)ffi.typeof
Signature
function ffi.typeof(value)Description
CType for a C type declaration, a CType, or a CData value. Types are interned, so equivalent declarations yield the same CType.Parameters
value- A C type declaration string, a
CType, or aCDatavalue.
Returns
A CType object.
Errors
- Raises an error if
valueis not a valid C type declaration,CTypeorCData.
Example
import ffi
const t = ffi.typeof("int")
print(t) // ctype<int>
const arr = ffi.cnew("double[4]")
print(ffi.typeof(arr)) // ctype<double[4]>
ffi.addressof
Signature
function ffi.addressof(cdata)Description
CData to the storage occupied by cdata. The pointer type is a pointer to the type of cdata. The pointer does not keep cdata alive, so it must not be used after cdata has been collected.Parameters
cdata- A
CDataobject whose address is requested.
Returns
A pointer CData to cdata.
Errors
- Raises an error if
cdatais not aCDataobject.
Example
import ffi
const value = ffi.cnew("int", 7)
const ptr = ffi.addressof(value)
print(ptr) // cdata<int*>: 0x...
ptr[0] = 99
print(value) // 99
ffi.gc
Signature
function ffi.gc(cdata, finalizer)Description
cdata when it is collected. Use it to release externally allocated resources, for example a pointer returned by malloc. Omitting the finalizer clears the current one. Setting a new finalizer replaces any previous one. The finalizer is called with cdata as its only argument.Parameters
cdata- The
CDataobject to attach the finalizer to. finalizer- (Optional) A callable, such as a Teascript function or a C function pointer, invoked with
cdataon collection. When omitted, the current finalizer is cleared.
Returns
The same cdata, so the call can be chained, as in return ffi.gc(ptr, ffi.C.free).
Errors
- Raises an error if
cdatais not aCDataobject.
Example
import ffi
ffi.cdef(```
void* malloc(size_t size);
void free(void* ptr);
```)
function allocate_string(str)
{
const buf = ffi.cast("char*", ffi.C.malloc(str.len + 1))
ffi.copy(buf, str)
// free() is called automatically when buf is collected
return ffi.gc(buf, ffi.C.free)
}
const str = allocate_string("Hello world!")
print(ffi.string(str))ffi.sizeof
Signature
function ffi.sizeof(ctype)Description
Parameters
ctype- A C type declaration or a
CType.
Returns
The size of ctype in bytes, as a number.
Errors
- Raises an error if
ctypeis not a valid or known C type.
Example
import ffi
print(ffi.sizeof("int")) // 4
print(ffi.sizeof("int[10]")) // 40
print(ffi.sizeof("void*")) // 8 on 64-bit targets
ffi.offsetof
Signature
function ffi.offsetof(ctype, field)Description
nil if the named field is not found. For types that are not records, no value is returned.Parameters
ctype- A record (
structorunion) type declaration or aCType. field- The name of the field to look up.
Returns
The byte offset of field as a number, nil if the record has no such field, or no value if ctype is not a record type.
Errors
- Raises an error if
ctypeis not a valid or known C type. - Raises an error if
fieldis not a string.
Example
import ffi
ffi.cdef(```
typedef struct {
char tag;
int value;
double ratio;
} Item;
```)
print(ffi.offsetof("Item", "tag")) // 0
print(ffi.offsetof("Item", "value")) // 4
print(ffi.offsetof("Item", "ratio")) // 8
print(ffi.offsetof("Item", "other")) // nil
ffi.alignof
Signature
function ffi.alignof(ctype)Description
Parameters
ctype- A C type declaration or a
CType.
Returns
The alignment of ctype in bytes, as a number.
Errors
- Raises an error if
ctypeis not a valid or known C type.
Example
import ffi
print(ffi.alignof("char")) // 1
print(ffi.alignof("int")) // 4
print(ffi.alignof("double")) // 8
ffi.istype
Signature
function ffi.istype(ctype, cdata)Description
cdata has exactly the same interned CType as ctype. No implicit conversions are considered, so int and const int, or int* and void*, are different types.Parameters
ctype- A C type declaration or a
CTypeto compare against. cdata- The
CDataobject whose type is checked.
Returns
true if the type of cdata is ctype, false otherwise.
Errors
- Raises an error if
ctypeis not a valid or known C type. - Raises an error if
cdatais not aCDataobject.
Example
import ffi
const n = ffi.cnew("int", 5)
print(ffi.istype("int", n)) // true
print(ffi.istype("double", n)) // false
ffi.tonumber
Signature
function ffi.tonumber(cdata)Description
nil for non-scalar types such as records, arrays, pointers and functions.Parameters
cdata- A
CDataobject holding a scalar value.
Returns
The value as a Teascript number, or nil if cdata is not a scalar numeric type.
Errors
- Raises an error if
cdatais not aCDataobject.
Example
import ffi
const n = ffi.cnew("uint8_t", 200)
print(ffi.tonumber(n)) // 200
const arr = ffi.cnew("int[2]")
print(ffi.tonumber(arr)) // nil
ffi.string
Signature
function ffi.string(cdata, length)Description
char*, void*, or char array. When length is given, exactly that many bytes are read from a pointer, array, or record’s storage, regardless of any NUL bytes, which allows reading binary data. For a char array, the string stops at the first NUL byte or at the end of the array, whichever comes first. Reading from a pointer does not check that the memory is valid.Parameters
cdata- A
char*,void*, orchararray. Withlength, any pointer, array, or record. length- (Optional) The exact number of bytes to read. When omitted, the string ends at the first NUL byte.
Returns
A string containing the bytes read.
Errors
- Raises an error if
cdatais not aCDataobject. - Raises an error if
cdatacannot be converted to a string, such as a pointer to a non-character type. - Raises an error if
lengthis given and is not an integer.
Example
import ffi
const p = ffi.cnew("char[16]")
ffi.copy(p, "Hello")
print(ffi.string(p)) // Hello
print(ffi.string(p, 3)) // Hel
ffi.copy
Signature
function ffi.copy(dst, src, length)Description
length, src must be a string: its bytes and a trailing NUL are copied. With length, src may be a string or CData, and exactly length bytes are copied with no trailing NUL. The destination must be large enough to receive the data, as no bounds are checked.Parameters
dst- The destination: a C pointer, array, or record.
src- The source: a string, or a
CDatawhenlengthis given. length- (Optional) The number of bytes to copy. When omitted,
srcmust be a string and its trailing NUL is copied as well.
Returns
The number of bytes copied, including the trailing NUL when length is omitted.
Errors
- Raises an error if
dstis not aCDataobject. - Raises an error if
lengthis omitted andsrcis not a string. - Raises an error if
lengthis given and is not an integer. - Raises an error if
lengthis given andsrcis neither a string nor aCDataobject.
Example
import ffi
const buf = ffi.cnew("char[32]")
const n = ffi.copy(buf, "Hello")
print(n) // 6, includes the trailing NUL
print(ffi.string(buf)) // Hello
const copy = ffi.cnew("char[32]")
ffi.copy(copy, buf, 5)
print(ffi.string(copy, 5)) // Hello
ffi.fill
Signature
function ffi.fill(dst, length, byte = 0)Description
length bytes at a C pointer, array, or record with byte. The destination must be at least length bytes long, as no bounds are checked.Parameters
dst- The destination: a C pointer, array, or record.
length- The number of bytes to fill.
byte- (Optional) The byte value to write. Defaults to
0.
Returns
Nothing.
Errors
- Raises an error if
dstis not aCDataobject. - Raises an error if
lengthorbyteis not an integer.
Example
import ffi
const buf = ffi.cnew("uint8_t[8]")
ffi.fill(buf, 8, 0xFF)
print(buf[0]) // 255
ffi.fill(buf, 8) // reset to zero
print(buf[0]) // 0
ffi.errno
Signature
function ffi.errno(value)Description
errno. If value is supplied, errno is set to it, and the value returned is the previous one. Call it immediately after the native call whose status you want to inspect, since other operations may modify errno.Parameters
value- (Optional) A new value to store into
errno.
Returns
The value of errno before any change was made, as a number.
Errors
- Raises an error if
valueis given and is not an integer.
Example
import ffi
ffi.errno(0) // clear errno
ffi.cdef("int close(int fd);")
ffi.C.close(-1) // fails
print(ffi.errno()) // 9 (EBADF) on most systems
ffi.abi
Signature
function ffi.abi(name)Description
"32bit", "64bit", "le" (little-endian), and "be" (big-endian).Parameters
name- The ABI name to test:
"32bit","64bit","le"or"be".
Returns
true if the target matches name, false otherwise.
Errors
- Raises an error if
nameis not a string.
Example
import ffi
if ffi.abi("64bit") and ffi.abi("le")
{
print("64-bit little-endian target")
}ffi.C
Signature
ffi.CDescription
CLib object giving access to the symbols of the C library already loaded in the process. Functions must be declared with ffi.cdef before they can be accessed.Returns
A CLib object.
Errors
- Accessing a function that has not been declared with
ffi.cdefraises an error.
Example
import ffi
ffi.cdef("int printf(const char* fmt, ...);")
ffi.C.printf("Integer: %d\n", 42)
ffi.C.printf("Float: %.2f\n", 3.14159)
ffi.C.printf("Character: %c\n", 65)CData
Signature
class CDataDescription
A value stored in C memory, returned by ffi.cnew, ffi.cast, ffi.addressof, and library function lookups, and by calls returning pointers or records. Scalar values are converted to Teascript numbers or booleans where appropriate.
Pointer and array values are indexed with zero-based integer indices, as in ptr[i] and array[i]. Pointer access is unchecked.
Record fields are accessed as attributes, as in record.x. Pointers to records support the same syntax, as in ptr.x. Assignments write through to C memory, and const-qualified data cannot be assigned to. Nested records and arrays are returned as CData that refer to the original storage.
C pointers can be compared with other C pointers and with nil; a null pointer compares equal to nil. Records, arrays, and function values do not compare equal.
Function-pointer data is called directly. Fixed parameters are converted according to the declared prototype. Variadic functions accept additional arguments with the default C promotions: booleans and integers are passed as integers, other numbers as double, strings and nil as pointers, and records and arrays as pointers to their storage. The call must supply all fixed arguments, and non-variadic functions require exactly the declared number.
tostring(cdata) produces a type-and-address representation such as cdata<int*>: 0x....
Returns
A CData object.
Errors
- Indexing a value that is neither a pointer nor an array raises an error.
- Indexing a
void*raises an error, and so does indexing with a value that is not a number. - Accessing a field that does not exist raises an error stating the C type has no such member.
- Accessing an attribute of a value that is neither a record nor a pointer to a record raises an error.
- Assigning to const-qualified data raises an error.
- Calling a value that is not a function pointer raises an error.
- Calling a function with the wrong number of arguments raises an error.
- Passing a value of an unsupported type as a variadic argument raises an error.
- Calling a function whose return type is not supported raises an error.
Example
import ffi
ffi.cdef(```
typedef struct {
int x;
int y;
} Point;
```)
const p = ffi.cnew("Point", { x = 1, y = 2 })
p.x = p.x + 10
print(p.x, p.y) // 11 2
const ptr = ffi.addressof(p)
print(ptr.y) // 2
print(ptr == nil) // false
const numbers = ffi.cnew("int[4]", [1, 2, 3, 4])
numbers[0] *= 10
print(numbers[0]) // 10
CType
Signature
class CTypeDescription
Describes a C type. A CType is accepted wherever a C type declaration can be used, and is returned by ffi.typeof. Types are interned, so equal types are represented by the same object, which is what ffi.istype relies on.
tostring(ffi.typeof("int")) produces ctype<int>.
The type parser supports scalar and pointer types, arrays, records (struct and union), typedefs, function declarations, and variadic function declarations, subject to the types supported by this module and libffi. Common C scalar types and fixed-width integer types such as int32_t, uint64_t, and size_t are predefined.
Returns
A CType object.
Errors
- Using a string that is not a valid or known C type declaration raises an error.
Example
import ffi
const t = ffi.typeof("uint64_t")
print(t) // ctype<uint64_t>
print(ffi.sizeof(t)) // 8
print(ffi.typeof(t) == t) // true
CLib
Signature
class CLibDescription
Represents a shared library, returned by ffi.load. The process C library is also available as ffi.C.
Reading a declared function name from a CLib looks up that symbol in the shared library and returns callable function-pointer CData. The result is cached on the library object. The function must have been declared beforehand with ffi.cdef, and the declaration must match the actual signature of the symbol in the library.
The library is unloaded when the CLib object is collected.
Returns
A CLib object.
Errors
- Looking up a name that has no prior declaration made by
ffi.cdefraises an error. - Looking up a declared name that does not exist in the library raises an error.
Example
import os, ffi
assert(os.name == "windows")
ffi.cdef(```
typedef void* HWND;
int MessageBoxA(HWND hWnd, const char* text, const char* caption, unsigned int type);
```)
const user32 = ffi.load("user32")
const MB_OK = 0x00000000
const MB_ICONINFORMATION = 0x00000040
const res = user32.MessageBoxA(
nil,
"Hello from Teascript FFI!",
"Teascript Windows API Example",
MB_OK | MB_ICONINFORMATION
)
if res == 1
{
print("User clicked OK")
}