ffi qjs-ffi

Libraries and symbols

Opening shared libraries and finding symbols in them. These are the functions behind everything else in ffi: CFunction and JSCallback work on the addresses they return.

dlopen(path, symbols[, types])

const { symbols, close } = dlopen(path, symbolSpecs);

Opens the library with RTLD_NOW, looks up every key of symbolSpecs and wraps it as a CFunction. The result is

PropertyDescription
symbolsAn object with one function per key of symbolSpecs, each named after its symbol. Not enumerable, so Object.keys(lib) is ["close"], as in bun.
close()dlclose()s the library and returns undefined, as in bun. Calling it again does nothing.
[Symbol.dispose]()The same as close(), so using lib = dlopen(...) closes it (the registered Symbol.for("Symbol.dispose") where the engine has none).
import { dlopen } from 'ffi';

const lib = dlopen('libm.so.6', {
  pow: { args: ['f64', 'f64'], returns: 'f64' },
});

console.log(lib.symbols.pow(2, 10)); // 1024
lib.close();

path is a library name or file name, as dlopen(3) takes it, or null for the symbols that are already loaded into the process:

const { symbols: { abs } } = dlopen(null, { abs: { args: ['i32'], returns: 'i32' } });

Each spec is { args, returns, abi }, exactly as for CFunction without ptr; the names are in Types and ABI. A library that cannot be opened throws an Error with code: "ERR_DLOPEN_FAILED" (as bun's) and the dlerror() text in its message; a symbol that is not in it throws a TypeError. Nothing stays open then.

linkSymbols

const { symbols } = linkSymbols(symbolSpecs);

Like dlopen(), without opening a library, and without close(). A spec is resolved from its own ptr if it has one (a non-NULL number or bigint; NULL, a string or anything else is a TypeError), and otherwise with dlsym(RTLD_DEFAULT, name). It makes functions from pointers you got elsewhere in one call:

import { linkSymbols, dlsym, RTLD_DEFAULT } from 'ffi';

const { symbols } = linkSymbols({
  myabs: { ptr: dlsym(RTLD_DEFAULT, 'abs'), args: ['i32'], returns: 'i32' },
  strlen: { args: ['cstring'], returns: 'u64' }, // found with dlsym(RTLD_DEFAULT, "strlen")
});

symbols.myabs(-7); // 7
symbols.strlen('hello'); // 5n

A symbol that is not found throws a TypeError. Only available where the platform defines RTLD_DEFAULT.

A third argument is an object of classes, dlopen(path, symbols, { Point }): a "Point *" in a spec is then a pointer typed by Point. linkSymbols(symbols, types) and cc({ ..., types }) take it the same way.

Variables

An extension: bun exposes only functions. A spec with type and no args or returns is a variable (a spec with both throws a TypeError). It works the same in dlopen(), linkSymbols() and cc():

const { symbols } = cc({
  source: 'counter.c', // int counter = 5; const double pi = 3.14; struct { float x, y; } origin;
  symbols: {
    counter: { type: 'i32' },
    pi: { type: 'f64', readonly: true },
    origin: { type: ['f32', 'f32'] },
    hello: { args: [], returns: 'i32' }, // functions as before
  },
});

symbols.counter; // 5, the memory is read each time
symbols.counter = 7; // and written

symbols.<name> is an enumerable accessor property, so it is live. A read converts the value as a returns of that type does, a write as an args of it does (a bigint for i64, a pointer for pointer; see Types).

  • readonly: true: a write throws a TypeError.
  • A struct type (an array, see structs) reads as an ArrayBuffer over the variable's own memory, with no copy: writes through a view reach the variable. This is also how a C array is exposed ({ array: "i32", length: 8 }, see array types). It cannot be assigned.
  • cstring reads the string a char * variable points to (null for NULL) and cannot be assigned. function reads as a pointer.
  • void (and buffer_length) is a TypeError.
  • address: true makes the property a plain pointer value, the address like dlsym() gives, for passing &counter to C or to read. A variable that is not in the library is a TypeError as for functions.

The address is the library's: after close() a variable dangles as the functions do.

Constants

An extension: a spec with value or enum is a constant, a plain #define or enum that has no symbol in the library, so nothing is dlsym()ed. It works the same in dlopen(), linkSymbols() and cc(), and dlopen(null, { ... }) with only constants is valid:

const { symbols } = dlopen('libfoo.so', {
  FOO_MAX: { value: 4096 },
  FOO_MASK: { value: 0xffffffffffffffffn, type: 'u64' },
  Color: { enum: { RED: 0, GREEN: 1, BLUE: 4 }, type: 'u32' },
  Flags: { enum: { A: 1, B: 2, C: 4 }, type: 'u8', flags: true },
});

symbols.FOO_MAX;    // 4096
symbols.Color.BLUE; // 4
symbols.Color[4];   // "BLUE" (reverse map, not enumerable)
KeyMeaning
valuea number, bigint, string or boolean, stored as is
typeoptional scalar the value must fit: { value: 300, type: "u8" } is a RangeError; 64-bit types give a bigint
enum{ NAME: value }; type defaults to i32; two names with one value are aliases, the reverse map keeps the first
flagsenum only; true requires disjoint bits, else RangeError

A constant is an enumerable, read-only data property of symbols (not a getter) and survives close(). value and enum together, or either mixed with args, returns or type-only variable keys, is a TypeError. qjs-ffi-genbindings writes these entries for #defines and enums.

Raw libdl

dlopen() takes a second argument of two kinds, told apart by its type: an object is the symbol table above, a number is the flags of the raw call. dlsym(), dlclose() and dlerror() are thin wrappers over libdl, described in the dlopen(3) manual page.

dlopen(path, flags)

const handle = dlopen('libz.so.1', RTLD_NOW | RTLD_GLOBAL);

Returns the library handle as a pointer (a number or a bigint), or null if it cannot be opened; dlerror() then tells why. path may be null for the main program.

dlsym(handle, name)

const fp = dlsym(handle, 'compress');

Returns the address of the symbol, or null if it is not found. handle is a library handle, or RTLD_DEFAULT or RTLD_NEXT: a number, a bigint (taken modulo 2^64, so 2n ** 64n - 1n is RTLD_NEXT) or null/undefined for RTLD_DEFAULT. A boolean, a string or an object is a TypeError. Pass the result to CFunction or as a ptr.

dlclose(handle)

dlclose(handle); // 0

Closes the library and returns dlclose(3)'s result (0 on success). A null handle is a TypeError.

dlerror()

Returns the text of the last libdl error as a string and clears it, or null if there is none.

const h = dlopen('libnope.so', RTLD_NOW); // null
console.log(dlerror()); // "libnope.so: cannot open shared object file: ..."
console.log(dlerror()); // null

errno()

errno(); // the C library's current errno

A function, not a property: call it right after the failing C call, before anything else that may set it.

suffix

The file name extension of shared libraries on the platform: "so" on Linux and "dll" on Windows. Use it to build a file name:

const path = `libsqlite3.${suffix}`;

RTLD constants

The flags of dlopen(path, flags) and the pseudo-handles of dlsym(). RTLD_LAZY, RTLD_NOW, RTLD_GLOBAL, RTLD_LOCAL, RTLD_NODELETE, RTLD_NOLOAD and RTLD_DEEPBIND are numbers to combine with |. RTLD_DEFAULT (0) and RTLD_NEXT (-1) are the handles that search the global scope and the libraries loaded after the caller. A constant is only exported where the platform's <dlfcn.h> defines it.