Foreign function interface
ffi is a QuickJS module that loads shared libraries, calls their C
functions, hands JavaScript functions back to C as function pointers, and reads
native memory. Its API follows bun:ffi: a
symbol table passed to dlopen() gives directly callable functions, with no
name lookup at call time, and 64-bit integers are BigInt.
import { dlopen } from 'ffi';
const { symbols, close } = dlopen('libm.so.6', {
pow: { args: ['f64', 'f64'], returns: 'f64' },
sqrt: { args: ['f64'], returns: 'f64' },
});
console.log(symbols.pow(2, 10)); // 1024
console.log(symbols.sqrt(144)); // 12
close();Everything is imported from "ffi":
import { dlopen, dlsym, dlclose, dlerror, errno,
linkSymbols, CFunction, JSCallback, cc,
ptr, toBuffer, toArrayBuffer, toPointer, toString, read, write, CString,
FFIType, suffix, pointerSize, JSContext, debug,
RTLD_LAZY, RTLD_NOW, RTLD_GLOBAL, RTLD_LOCAL,
RTLD_NODELETE, RTLD_NOLOAD, RTLD_DEEPBIND,
RTLD_DEFAULT, RTLD_NEXT } from 'ffi';The module also has a default export, an object holding all of these (the same
values), as bun:ffi does: import ffi from "ffi"; ffi.dlopen(...).
cc exists only in a build with ENABLE_TCC, and the RTLD_* constants only
where the platform defines them. Run scripts with qjsm, see
Installation.
Contents
| Page | What it covers |
|---|---|
| Libraries and symbols | dlopen(), linkSymbols(), dlsym(), dlclose(), dlerror(), errno(), suffix, RTLD_* |
| Types and ABI | FFIType and its numbers, the type names, structs by value, ABI names |
| CFunction | a function pointer as a callable function |
| JSCallback | a JavaScript function as a function pointer |
| Classes as types | a buffer class (usually extending ArrayBuffer) as a type in a spec |
| Pointers and memory | ptr(), toArrayBuffer(), read, write, CString, toString(), toPointer(), pointerSize |
| C compiler | cc(): compile and run C from JavaScript |
| Miscellaneous | JSContext(), debug() |
| Generating bindings | tools/gen-bindings.js, a binding generator for C and C++ headers |
| Legacy API | define() and call(), in the module ffi/legacy.js |
| node:ffi | the API of Node's node:ffi on top of ffi, in the module node/ffi.js |
Usage
dlopen(path, symbols[, types]) opens a library and returns { symbols, close }.
Each entry of the symbol table becomes a function (the optional third argument
is an object of classes that a "Point *"
names):
import { dlopen, FFIType, suffix } from 'ffi';
const path = `libsqlite3.${suffix}`;
const { symbols: { sqlite3_libversion } } = dlopen(path, {
sqlite3_libversion: {
args: [],
returns: FFIType.cstring,
},
});
console.log(`SQLite 3 version: ${sqlite3_libversion()}`);path may be null to search the symbols already loaded into the process
(libc, and whatever the interpreter links). A missing library throws an Error
with code: "ERR_DLOPEN_FAILED", a missing symbol a TypeError. See Libraries and symbols.
Types
A signature is { args: [...], returns }, written with the names of
Types and ABI: the sized integers i8..u64, f32, f64, bool,
pointer, cstring, void (return only) and C-style aliases such as int and
double, or the matching FFIType number (FFIType.i32, which is 5). A struct
passed or returned by value is an array of member types.
| Type | C type | JavaScript |
|---|---|---|
i8..i32, u8..u32 | int8_t..uint32_t | number |
i64, u64 | int64_t, uint64_t | bigint |
i64_fast, u64_fast | int64_t, uint64_t | number, or an exact bigint past 2^53 |
f32, f64 | float, double | number |
bool | bool | boolean |
pointer, ptr, function | void * | null, number or bigint |
cstring | char * | string |
Function pointers
CFunction() wraps a pointer you already have, for example from dlsym():
import { dlsym, CFunction, RTLD_DEFAULT } from 'ffi';
const strdup = CFunction({
ptr: dlsym(RTLD_DEFAULT, 'strdup'),
args: ['cstring'],
returns: 'cstring',
});
console.log(strdup('hello'));linkSymbols() is dlopen() without opening a library: every entry is
resolved from its own ptr, or else with dlsym(RTLD_DEFAULT, name):
import { linkSymbols } from 'ffi';
const { symbols: { gnu_get_libc_version } } = linkSymbols({
gnu_get_libc_version: { args: [], returns: 'cstring' },
});
console.log(gnu_get_libc_version());See CFunction and Libraries and symbols.
Callbacks
JSCallback turns a JavaScript function into a native function pointer, which
.ptr gives, to pass to C:
import { JSCallback, CFunction, dlsym, read, RTLD_DEFAULT } from 'ffi';
const compare = new JSCallback((a, b) => read.i32(a) - read.i32(b), {
args: ['pointer', 'pointer'],
returns: 'i32',
});
const qsort = CFunction({ ptr: dlsym(RTLD_DEFAULT, 'qsort'), args: ['pointer', 'u64', 'u64', 'pointer'], returns: 'void' });
const numbers = new Int32Array([5, 3, 9, 1]);
qsort(numbers, numbers.length, 4n, compare);
console.log(numbers); // 1, 3, 5, 9
compare.close();Call close() when the callback is no longer needed. See
JSCallback for the details, including exceptions thrown by
the function.
Strings
cstring converts at the boundary: a JavaScript string argument is encoded as
a NUL-terminated UTF-8 string for the duration of the call, and a cstring
result is decoded into a new JavaScript string. For a char * that you hold as
an address, CString(ptr) decodes it, and toString(ptr, length) decodes
an exact number of bytes. A char * type spelled that way is a plain pointer.
See Pointers and memory.
Pointers
A pointer is null, a number (exact up to 2^53 - 1, which every user-space
address is), and a bigint above that. ptr() takes the address of an ArrayBuffer or typed
array, toArrayBuffer() makes an ArrayBuffer over memory at an address, and
read reads a value straight from an address:
import { ptr, read, toArrayBuffer } from 'ffi';
const bytes = new Uint8Array([1, 2, 3, 4]);
const p = ptr(bytes);
console.log(read.u8(p, 2)); // 3
console.log(read.u32(p, 0)); // 67305985 (0x04030201)
const view = new Uint8Array(toArrayBuffer(p, 1, 2)); // [2, 3], aliasing `bytes`See Pointers and memory.
Compiling C
cc() compiles C source in memory with TinyCC and returns its functions, with
the same signatures:
import { cc } from 'ffi';
const { symbols: { hello } } = cc({
source: 'hello.c',
symbols: { hello: { args: [], returns: 'int' } },
});
console.log(hello()); // 42It needs a build with -DENABLE_TCC=ON. See C compiler.
Memory management
ffi does not manage native memory: whatever C allocates, you free, and a
pointer outlives nothing. In particular
toArrayBuffer()makes a view over the memory, not a copy. Keep the memory alive while the buffer is used,.slice(0)the buffer to copy it, or pass a native deallocator to be called when the buffer is garbage collected, see Pointers and memory.- A
JSCallbackpointer is valid untilclose(), even when nothing references the object any more (a callback is never freed by the garbage collector). - After
dlopen()'sclose()the library's functions and data are gone. - A pointer derived from a
cstringargument is valid only for that call.
Notes
- 64-bit values:
i64/u64are exactbigints. An argument may be anumberor abigint. - Structs by value are supported, with the member types spelled out, and so are
variadic functions (
variadic: true). - Little-endian targets only. Linux x86_64 is the main target; mingw64 cross builds compile but are untested.
qjsm, notqjs, runs the scripts and tests of this project.
Differences from bun:ffi
This module follows bun:ffi but is not a drop-in replacement yet. The open items are tracked in TODO.md:
Not implemented:
JSCallback'sthreadsafeoption works as a property only: it reads back astrue, and the callback still runs on the JS thread alone.viewSourceis missing.
Extensions, which bun does not have (none of them changes what a bun:ffi script does):
- a spec with
typeinstead ofargs/returnsexposes a variable; - variadic functions (
variadic: true) and structs by value; - a buffer class, usually extending
ArrayBuffer, as the type of an argument, a return or a variable, and thetypesobject that names such classes in a spec (dlopen(path, symbols, types), `linkSymbols(symbols, types),cc({ ..., types })`); - the node:ffi API.
Different on purpose or for now:
toBuffer()returns anArrayBuffer(QuickJS has noBuffer).read.ptrand every pointer result are exact (abigintabove 2^53 - 1); bun'sread.ptrrounds to anumber.- A closed
JSCallbackpassed as a pointer is aTypeError; bun passes a stale pointer. An out-of-rangebigintpointer wraps modulo 2^64, as in bun.