Ffi

FFI polyfill for loading and calling native shared libraries. Only available on Zune; calling any function from an unsupported runtime will raise an error.

Use dlopen to load a shared library and bind its exported C functions. Use struct to describe C struct layouts, closure to expose Luau callbacks as C function pointers, and alloc/create/free to manage raw memory for out-parameters and byte buffers.

Summary

Functions

Ffi.getTypes() → _zune_ffi_typesFfi.getNull() → FFIPointerFfi.getPrefix() → stringFfi.getSuffix() → stringFfi.dlopen(path: string, functions: { [string]: FFIFunctionDefinition }) → FFILibraryFfi.struct(fields: { { [string]: FFIAnyDataType } }) → FFIStructureTypeFfi.closure(definition: FFIFunctionDefinition, handler: (...any) -> any) → FFIPointerFfi.fn(definition: FFIFunctionDefinition, srcPtr: FFIPointer) → (...any) -> anyFfi.alloc(size: number, alignment: number?) → FFIPointerFfi.create(dataType: FFIAnyDataType) → FFIPointerFfi.free(src: FFIPointer)Ffi.dupe(src: buffer | FFIPointer | vector) → FFIPointerFfi.ptr(src: FFIPointer) → FFIPointerFfi.ptrFromAddress(src: buffer) → FFIPointerFfi.tagName(tag: number) → string?Ffi.getLuaState(mainthread: boolean?) → FFIPointer

Functions

getTypes

Ffi . getTypes ( )  -> _zune_ffi_types

Returns the primitive FFI type descriptors. Use the returned table’s fields as returns and args values in dlopen, closure, and fn definitions. Available types: void, i8, u8, i16, u16, i32, u32, i64, u64, float, double, pointer.

Returns

_zune_ffi_types

getNull

Ffi . getNull ( )  -> FFIPointer

Returns a null (0x0) FFI pointer. Pass this wherever a C function expects a NULL pointer argument.

Returns

FFIPointer

getPrefix

Ffi . getPrefix ( )  -> string

Returns the platform-specific shared library filename prefix, e.g. "lib" on Linux and macOS, "" on Windows.

Returns

string

getSuffix

Ffi . getSuffix ( )  -> string

Returns the platform-specific shared library filename suffix, e.g. ".so" on Linux, ".dylib" on macOS, ".dll" on Windows.

Returns

string

dlopen

Ffi . dlopen ( path ,  functions )  -> FFILibrary

Opens a native shared library at path and binds the listed exported C functions. Each entry in functions maps a symbol name to its return type and argument types. Returns an FFILibrary whose fields are callable bound functions.

local lib = ffi.dlopen("/usr/lib/libfoo.so", {
    fooInit = { returns = ffi.getTypes().void, args = {} },
    fooAdd  = { returns = ffi.getTypes().i32, args = { ffi.getTypes().i32, ffi.getTypes().i32 } },
})
lib.fooInit()
print(lib.fooAdd(1, 2))

Parameters

path: string
functions: { { [string]: FFIFunctionDefinition } }

Returns

FFILibrary

struct

Ffi . struct ( fields )  -> FFIStructureType

Defines a C struct layout from an ordered list of named fields. Each entry is a single-key table mapping the field name to its FFIAnyDataType. Returns an FFIStructureType you can pass to create or use with :new() to allocate an initialised buffer.

local Vec2 = ffi.struct({ { x = ffi.getTypes().f32 }, { y = ffi.getTypes().f32 } })
local v = Vec2:new({ x = 1, y = 2 })

Parameters

fields: { { { [string]: FFIAnyDataType } }

Returns

FFIStructureType

closure

Ffi . closure ( definition ,  handler )  -> FFIPointer

Wraps a Luau function as a C-callable function pointer. The definition describes the C signature the native side will use to call back into Luau. Returns an FFIPointer that remains valid until garbage-collected; retain it for the lifetime of any native code that may invoke it.

local cb = ffi.closure(
    { returns = ffi.getTypes().void, args = { ffi.getTypes().pointer, ffi.getTypes().u64 } },
    function(dataPtr, length) ... end
)

Parameters

definition: FFIFunctionDefinition
handler: any) -> any

Returns

FFIPointer

fn

Ffi . fn ( definition ,  srcPtr )  -> any) -> any

Wraps a raw FFIPointer to a C function as a callable Luau function according to definition. Useful when a library hands you a function pointer at runtime.

Parameters

definition: FFIFunctionDefinition
srcPtr: FFIPointer

Returns

any) -> any

alloc

Ffi . alloc ( size ,  alignment )  -> FFIPointer

Allocates size bytes of native memory aligned to alignment bytes (defaults to 1). Returns an FFIPointer to the allocation. Must be freed with ffi.free when no longer needed.

Parameters

size: number
alignment: number?

Returns

FFIPointer

create

Ffi . create ( dataType )  -> FFIPointer

Allocates native memory large enough for a value of dataType and returns a pointer to it. Useful for allocating out-parameter slots (size_t*, uint8_t**, etc.).

Parameters

dataType: FFIAnyDataType

Returns

FFIPointer

free

Ffi . free ( src )  -> ()

Frees native memory previously allocated with alloc or create.

Parameters

src: FFIPointer

dupe

Ffi . dupe ( src )  -> FFIPointer

Copies a Luau buffer, FFIPointer, or vector into a freshly allocated native memory region and returns a pointer to the copy.

Parameters

src: buffer | FFIPointer | vector

Returns

FFIPointer

ptr

Ffi . ptr ( src )  -> FFIPointer

Returns a pointer to the memory backing src. Use dupe instead if you need an owned copy.

Parameters

src: FFIPointer

Returns

FFIPointer

ptrFromAddress

Ffi . ptrFromAddress ( src )  -> FFIPointer

Constructs an FFIPointer from a raw address stored in an 8-byte buffer (little-endian uint64). Use this to materialise a pointer returned as a buffer by readu64.

Parameters

src: buffer

Returns

FFIPointer

tagName

Ffi . tagName ( tag )  -> string?

Returns the tag name string associated with tag, or nil if the tag was never registered. Useful for debugging tagged pointer types created with pointer:newTag.

Parameters

tag: number

Returns

string?

getLuaState

Ffi . getLuaState ( mainthread )  -> FFIPointer

Returns an FFIPointer to the current Lua state. When mainthread is true, returns the main thread’s state rather than the current coroutine’s. Required for some C APIs that expect a lua_State*.

Parameters

mainthread: boolean?

Returns

FFIPointer