Legacy API
The original interface registers functions by name, with define(), and calls
them by name, with call(). It is not part of the ffi module any more: it
lives in the JavaScript module legacy.js, which builds each function on a
CFunction. Prefer dlopen() or CFunction
directly; this page is for code that still uses define() and call().
import { dlsym, RTLD_DEFAULT } from 'ffi';
import { define, call } from 'ffi/legacy';
define('strlen', dlsym(RTLD_DEFAULT, 'strlen'), null, 'int', 'char *');
console.log(call('strlen', 'hello')); // 5ffi/legacy.js is installed in the QuickJS JS module directory and copied to
the build directory, so one QUICKJS_MODULE_PATH finds both it and ffi.so. In the
source tree, import it by path (../lib/ffi/legacy.js).
define()
define(name, functionPointer, abi, returnType, ...parameterTypes);Registers the function at functionPointer under name and returns true.
abi is an ABI name or null for the default. It returns
false, with a message on stderr, if a type is unknown or cannot be used.
- A
nullor NULLfunctionPointerthrows aTypeError. - A name that is already defined is left as it is and
trueis returned. - Up to 30 parameters can be defined; more are ignored.
call()
const n = call(name, ...params);Calls the function registered as name. An unknown name throws an Error.
- The result is always a number (a
double), which presumes that all integers and pointers fit into 52 bits. A function returningvoidgives0, and a NULL pointer gives0. Only a return type of"string"or"char *"gives a string (nullfor NULL). - A JavaScript string passed for a pointer parameter is copied, with its terminating NUL, and the pointer is that of the copy. The callee cannot change the string.
- An
ArrayBufferor typed array is passed by its address, and its contents can be written. - A
JSCallbackis passed as its function pointer. trueandfalseare 1 and 0,nullis NULL.
Types
Legacy types are the libffi names ("sint8", "uint32", "double",
"pointer", ...), C-like aliases ("int", "long", "size_t",
"unsigned char", "char *", "void *") and the semantic types "string"
(a JavaScript string) and "buffer" (an ArrayBuffer). Any other name ending
in * is a pointer as well ("struct foo *"). These are not the type names
of Types and ABI.
Two things differ from the C implementation this replaced: "longdouble" is
refused (a CFunction has no such type), and "size_t" is 64 bits wide (it
was a 32-bit uint).