ffi.library

import ffi.library

ffi lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled ffi.library.* needs import ffi.library.

A loaded shared library, and binding what it exports.

Classes

Library

class ffi.Library

A shared library loaded into the process, or the process itself.

Libraries come from ffi.open() and ffi.link(). Functions are bound from one either one at a time with function(), or in bulk from declarations with declare(), declare_rust() and bind().

A library stays loaded while anything bound from it is still reachable, even after close(): closing only stops further use.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

ffi.Library()

Library.path()

ffi.Library.path() -> string|nil

The path the library was loaded from, as the loader was given it, or nil for the running process.

Returns string|nil

Library.close()

ffi.Library.close()

Stops the library being used. Every function bound from it raises LoadError when called from now on. The code is unloaded once nothing refers to the library any longer.

Library.is_closed()

ffi.Library.is_closed() -> bool

Whether close() has been called.

Returns bool

Library.function()

ffi.Library.function(name: string, returns, params: list, options) -> function

Binds one function by name and signature, returning it as a Zuri function.

var strlen = libc.function('strlen', ffi.size_t, [ffi.string])
echo strlen('hello')

For a variadic function, params lists only the fixed parameters. Each extra argument travels as the type its value suggests: an integral number that fits an int as int, a larger one as long long, any other number as double, a bool as int, a string as const char *, and a pointer, bytes or nil as void *. Give any other type with Type.of().

On glibc, name@VERSION binds that version of a versioned symbol.

Parameters

• name (string)
• returns (Type)
• params (list) — The parameter types.
• options (dict|nil) — variadic (default false) and abi, the calling convention: 'default', or on x86-64 'win64' or 'sysv64'.

Returns function

Raises SymbolError when the library does not export name.

Raises FfiError when libffi cannot call the signature.

Library.variable()

ffi.Library.variable(name: string, type) -> Pointer

A pointer to a global variable the library exports, typed as the variable, so get() reads it and set() writes it.

Parameters

• name (string)
• type (Type)

Returns Pointer

Raises SymbolError when the library does not export name.

Library.symbol()

ffi.Library.symbol(name: string, type) -> Pointer|nil

The address of an exported symbol, or nil when there is none.

Parameters

• name (string)
• type (Type|nil) — The type to give the pointer.

Returns Pointer|nil

Library.has()

ffi.Library.has(name: string) -> bool

Whether the library exports name.

Parameters

• name (string)

Returns bool

Library.declare()

ffi.Library.declare(source: string, options) -> module

Reads C declarations and binds them to this library in one step, returning the namespace Declarations.bind() does.

var c = libc.declare('
  size_t strlen(const char *s);
  int abs(int n);
')

echo c.strlen('hello')

Parameters

• source (string)
• options (dict|nil) — allow_missing as for bind(), and include, a list of Declarations whose types the source may use.

Returns module

Raises DeclarationError when the source cannot be read.

Raises SymbolError when a declared function or variable is missing.

Library.declare_rust()

ffi.Library.declare_rust(source: string, options) -> module

Reads Rust declarations and binds them to this library in one step.

var geometry = ffi.open('geometry').declare_rust('
  #[repr(C)]
  pub struct Point { pub x: f64, pub y: f64 }

  #[no_mangle]
  pub extern "C" fn distance(a: Point, b: Point) -> f64 { 0.0 }
')

Parameters

• source (string)
• options (dict|nil) — As for declare().

Returns module

Raises DeclarationError when the source cannot be read.

Raises SymbolError when a declared function or variable is missing.

Library.bind()

ffi.Library.bind(declarations, options) -> module

Binds everything declarations holds to this library; the same as declarations.bind(library, options).

Parameters

• declarations (Declarations)
• options (dict|nil) — As for Declarations.bind().

Returns module

Library.to_string()

ffi.Library.to_string()

2026, Richard Ore and Zuri contributors