{ "type": "module", "source": "doc/api/ffi.md", "modules": [ { "textRaw": "FFI", "name": "ffi", "introduced_in": "v26.1.0", "type": "module", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "desc": "

The node:ffi module provides an experimental foreign function interface for\nloading dynamic libraries and calling native symbols from JavaScript.

\n

This API is unsafe. Passing invalid pointers, using an incorrect symbol\nsignature, or accessing memory after it has been freed can crash the process\nor corrupt memory.

\n

To access it:

\n
import ffi from 'node:ffi';\n
\n
const ffi = require('node:ffi');\n
\n

This module is only available under the node: scheme in builds with FFI\nsupport. It can be disabled with the --no-experimental-ffi flag.

\n

Building Node.js with node:ffi support is available via the bundled libffi on\nplatforms where libffi provides a compatible static backend, or via a\nshared libffi using the --shared-ffi configure flag.\nThe unofficial GN build does not support node:ffi.

\n

The following targets are not supported by bundled libffi:

\n\n

When using the Permission Model, FFI APIs are\nrestricted unless the --allow-ffi flag is provided.

", "modules": [ { "textRaw": "Overview", "name": "overview", "type": "module", "desc": "

The node:ffi module exposes two groups of APIs:

\n", "displayName": "Overview" }, { "textRaw": "Type names", "name": "type_names", "type": "module", "desc": "

FFI signatures use string type names.

\n

Supported type names:

\n\n
\nAlternative spellings\n\n
\n

These type names are also exposed as constants on ffi.types:

\n\n

Pointer-like types (pointer, string, buffer, arraybuffer, and\nfunction) are all passed through the native layer as pointers.

\n

When Buffer, ArrayBuffer, or typed array values are passed as pointer-like\narguments, Node.js borrows a raw pointer to their backing memory for the\nduration of the native call. The caller must ensure that backing store remains\nvalid and stable for the entire call.

\n

It is unsupported and dangerous to resize, transfer, detach, or otherwise\ninvalidate that backing store while the native call is active, including\nthrough reentrant JavaScript such as FFI callbacks. Doing so may crash the\nprocess, produce incorrect output, or corrupt memory.

\n

The char type follows the platform C ABI. On platforms where plain C char\nis signed it behaves like int8; otherwise it behaves like uint8.

\n

The bool type is marshaled as an 8-bit unsigned integer. Pass numeric values\nsuch as 0 and 1; JavaScript true and false are not accepted.

\n

On optimized Fast FFI calls, pointer and function parameters accept raw\npointer bigint values. For pointer-like parameters, null, undefined,\nstrings, Buffer, typed array, DataView, and ArrayBuffer values are converted\non the JavaScript side before calling the optimized native wrapper.

\n

Optimized Fast FFI calls fall back to another call path when a\nfunction's arguments or return type do not fit the platform-specific fast\ntrampoline. Fast FFI calls support at most 8 total arguments, and the\nregister and argument limits differ per architecture:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ArchitectureMax integer/pointer argsMax floating-point argsBuffer-shaped argsBuffer-shaped + FP togetherNarrow (8/16-bit) return
AArch647 (6 when a buffer-shaped arg is present)8SupportedNot supportedSupported
x86-64, Linux/macOS (SysV)6 (4 when a buffer-shaped arg is present)8SupportedNot supportedSupported
x86-64, Windows (Win64)3 (total arguments also capped at 3)3Not supportedN/ASupported
s390x44Not supportedN/ANot supported
PPC64LE78Not supportedN/ANot supported
LoongArch6478Not supportedN/ANot supported
RISC-V (64-bit)78Not supportedN/ANot supported
\n

PPC64BE has no fast-call trampoline and always uses the generic call path.\n\"Buffer-shaped args\" means Buffer, typed array, DataView, or ArrayBuffer\nvalues passed as pointer-like arguments. Functions whose argument or return\ntypes exceed the limits for the current platform use one of the other\ncall paths instead.

", "displayName": "Type names" }, { "textRaw": "Signature objects", "name": "signature_objects", "type": "module", "desc": "

Functions and callbacks are described with signature objects.

\n

Signature objects may contain the following properties, both of which are\noptional:

\n\n
const signature = {\n  return: 'int32',\n  arguments: ['int32', 'int32'],\n};\n
", "displayName": "Signature objects" }, { "textRaw": "Calling native functions", "name": "calling_native_functions", "type": "module", "desc": "

Argument conversion depends on the declared FFI type.

\n

For 8-, 16-, and 32-bit integer types and for floating-point types, pass\nJavaScript number values that match the declared type.

\n

For 64-bit integer types (int64 and uint64), pass JavaScript bigint\nvalues.

\n

For pointer-like arguments:

\n\n

Pointer return values are exposed as bigint addresses.

", "displayName": "Calling native functions" }, { "textRaw": "Call paths", "name": "call_paths", "type": "module", "desc": "

When a symbol is resolved through ffi.dlopen(),\nlibrary.getFunction(), or library.getFunctions(), Node.js selects\none of three native call paths for the returned wrapper. The selection is based\non the declared signature, on the current platform, and on the capabilities of\nthe current process. It is made once when the function is created, cannot be\nconfigured, and is not observable from JavaScript.

\n

The call paths are designed to accept the same JavaScript values for each\ntype name, to perform the same validation, and to throw the same\nerrors, so that applications do not need to know which call path a particular\nfunction uses. They differ in how much work is done per call. The paths exist\nso that common signatures can be called with as little overhead as possible\nwhile every supported signature keeps working.

\n

Node.js tries the call paths in the following order and uses the first one that\nsupports the signature:

\n
    \n
  1. The Fast API call path, which lets optimized JavaScript call the native\nsymbol directly through a generated per-signature trampoline.
    2. \n
  2. The shared buffer call path, which passes arguments through a\npreallocated buffer instead of converting each argument across the\nJavaScript and C++ boundary on every call.
    3. \n
  3. The generic call path, which converts each argument in C++ and calls the\nsymbol through libffi. This path supports every signature.
    4. \n
\n

The contributor guide FFI Fast API internals describes the implementation of\nthese call paths in detail.

", "modules": [ { "textRaw": "Fast API call path", "name": "fast_api_call_path", "type": "module", "desc": "

The Fast API call path binds the wrapper as a V8 Fast API function. When\nJavaScript code calling the wrapper is optimized by V8, the call goes from the\noptimized code straight into a small native trampoline that Node.js generates\nfor the exact signature when the function is created. The trampoline moves the\narguments into the registers expected by the native symbol and calls it. For\nthe scalar entry point, there is no intermediate argument conversion in C++.

\n

Functions on this path keep a conventional native entry point as well. Calls\nfrom code that V8 has not optimized, or that V8 deoptimizes, use that entry\npoint, which behaves like the generic call path. This is transparent to the\ncaller.

\n

Pointer-like arguments are prepared in JavaScript before the trampoline runs:

\n\n

For signatures with a single pointer, buffer, or arraybuffer argument,\nNode.js also creates an alternate Fast API entry point that receives Buffer,\ntyped array, DataView, and ArrayBuffer values directly. The JavaScript\nwrapper dispatches to it when the argument is such a value, and a native helper\nextracts the pointer from the backing store instead of converting the value in\nJavaScript.

\n

A function uses this call path only when all of the following conditions are\nmet:

\n\n

The register limits are platform-specific. Integer and pointer-like arguments\nshare one set of registers, and floating-point arguments share another. The\nlimits for each architecture are listed in Type names.

\n

A signature that fails any of these checks is not an error. The function is\ncreated on the next call path that supports it.

", "displayName": "Fast API call path" }, { "textRaw": "Shared buffer call path", "name": "shared_buffer_call_path", "type": "module", "desc": "

The shared buffer call path is used for signatures that the Fast API call path\ndoes not support. When the function is created, Node.js allocates a small\nper-function buffer with one 8-byte slot for the return value and one 8-byte\nslot for each argument. On every call, the JavaScript wrapper validates the\narguments, writes them into their slots, invokes the native symbol through\nlibffi without passing any JavaScript arguments, and then reads the return\nvalue back from the buffer. This avoids converting each argument individually\nacross the JavaScript and C++ boundary.

\n

A function uses this call path when all of the following conditions are met:

\n\n

All type names are supported on this path, and there is no limit on the number\nof arguments.

\n

Pointer-like arguments (pointer, string, buffer, arraybuffer, and\nfunction) are written to the shared buffer only when the value is a bigint,\nnull, or undefined. When a call passes a string, Buffer, typed array,\nDataView, or ArrayBuffer to a pointer-like parameter, that individual call\nis handed off to the generic call path, which performs the conversion in\nC++. The function itself stays on the shared buffer call path for later calls.

\n

The shared buffer is private to each function. Reentrant calls to the same\nfunction, for example from an FFI callback, are safe because the native side\ncopies the arguments out of the buffer before invoking the symbol.

", "displayName": "Shared buffer call path" }, { "textRaw": "Generic call path", "name": "generic_call_path", "type": "module", "desc": "

The generic call path converts each JavaScript argument to its native\nrepresentation in C++ and calls the symbol through libffi. It supports every\nsignature that node:ffi accepts and is the reference implementation for the\nargument validation and error behavior that the other call paths reproduce.

\n

A function is created directly on this call path when the Fast API call path\nis unavailable and either the host is big-endian or the signature has no\narguments.

\n

The generic call path also serves individual calls handed off by the other call\npaths, such as unoptimized or deoptimized call sites of a Fast API function and\nshared buffer calls that pass non-bigint pointer-like values.

\n

Callbacks created with library.registerCallback() are always implemented\nwith libffi closures. They are independent of the call path used by any\nfunction.

", "displayName": "Generic call path" } ], "displayName": "Call paths" }, { "textRaw": "Primitive memory access helpers", "name": "primitive_memory_access_helpers", "type": "module", "desc": "

The following helpers read and write primitive values at a native pointer,\noptionally with a byte offset:

\n\n

These helpers perform direct memory reads and writes. pointer must be a\nbigint referring to valid readable or writable native memory. offset, when\nprovided, is interpreted as a byte offset from pointer.

\n

The getter helpers return JavaScript number values for 8-, 16-, and 32-bit\ninteger types and for floating-point types. They return bigint values for\n64-bit integer types.

\n

The setter helpers require an explicit byte offset and validate the supplied\nJavaScript value against the target native type before writing it into memory.\nFor setInt64() and setUint64(), bigint values are accepted directly;\nnumeric inputs must be integers within JavaScript's safe integer range.

\n
const {\n  getInt32,\n  setInt32,\n} = require('node:ffi');\n\nsetInt32(ptr, 0, 42);\nconsole.log(getInt32(ptr, 0));\n
\n

Like the other raw memory helpers in this module, these APIs do not track\nownership, bounds, or lifetime. Passing an invalid pointer, using the wrong\noffset, or writing through a stale pointer can corrupt memory or crash the\nprocess.

", "displayName": "Primitive memory access helpers" }, { "textRaw": "Safety notes", "name": "safety_notes", "type": "module", "desc": "

The node:ffi module does not track pointer validity, memory ownership, or\nnative object lifetimes.

\n

In particular:

\n\n

As a general rule, prefer copied values unless zero-copy access is required,\nand keep callback and pointer lifetimes explicit on the native side.

", "displayName": "Safety notes" } ], "properties": [ { "textRaw": "{string}", "name": "suffix", "type": "string", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "desc": "

The native shared library suffix for the current platform:

\n\n

This can be used to build portable library paths:

\n
const { suffix } = require('node:ffi');\n\nconst path = `libsqlite3.${suffix}`;\n
" } ], "methods": [ { "textRaw": "`ffi.dlopen(path[, definitions])`", "name": "dlopen", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [ { "version": "REPLACEME", "pr-url": "https://github.com/nodejs/node/pull/65909", "description": "Library paths inside a mounted virtual file system are now supported." } ] }, "signatures": [ { "params": [ { "textRaw": "`path` {string | null} Path to a dynamic library, or `null` to resolve symbols from the current process image.", "name": "path", "type": "string | null", "desc": "Path to a dynamic library, or `null` to resolve symbols from the current process image." }, { "textRaw": "`definitions` {Object} Symbol definitions to resolve immediately.", "name": "definitions", "type": "Object", "desc": "Symbol definitions to resolve immediately.", "optional": true } ], "return": { "textRaw": "Returns: {Object}", "name": "return", "type": "Object" } } ], "desc": "

Loads a dynamic library and resolves the requested function definitions.

\n

On Windows passing null is not supported.

\n

A path inside a mounted virtual file system is supported: the\noperating system's dynamic loader cannot open a virtual path, so the\nlibrary's bytes are read from the VFS and loaded from a private,\nself-cleaning temporary image instead, while lib.path keeps reporting\nthe virtual path. Libraries on the real file system are unaffected and\nload directly.

\n

When definitions is omitted, functions is returned as an empty object until\nsymbols are resolved explicitly.

\n

The returned object contains:

\n\n

The returned object also implements the explicit resource management protocol,\nso it can be used with the using declaration. Disposing the returned\nobject closes the library handle.

\n
import { dlopen, suffix } from 'node:ffi';\n\n{\n  using handle = dlopen(`./mylib.${suffix}`, {\n    add_i32: { arguments: ['int32', 'int32'], return: 'int32' },\n  });\n  console.log(handle.functions.add_i32(20, 22));\n} // handle.lib.close() is invoked automatically here.\n
\n
import { dlopen, suffix } from 'node:ffi';\n\nconst { lib, functions } = dlopen(`./mylib.${suffix}`, {\n  add_i32: { arguments: ['int32', 'int32'], return: 'int32' },\n  string_length: { arguments: ['pointer'], return: 'uint64' },\n});\n\nconsole.log(functions.add_i32(20, 22));\n
\n
const { dlopen, suffix } = require('node:ffi');\n\nconst { lib, functions } = dlopen(`./mylib.${suffix}`, {\n  add_i32: { arguments: ['int32', 'int32'], return: 'int32' },\n  string_length: { arguments: ['pointer'], return: 'uint64' },\n});\n\nconsole.log(functions.add_i32(20, 22));\n
" }, { "textRaw": "`ffi.dlclose(handle)`", "name": "dlclose", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`handle` {DynamicLibrary}", "name": "handle", "type": "DynamicLibrary" } ] } ], "desc": "

Closes a dynamic library.

\n

This is equivalent to calling handle.close().

" }, { "textRaw": "`ffi.dlsym(handle, symbol)`", "name": "dlsym", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`handle` {DynamicLibrary}", "name": "handle", "type": "DynamicLibrary" }, { "textRaw": "`symbol` {string}", "name": "symbol", "type": "string" } ], "return": { "textRaw": "Returns: {bigint}", "name": "return", "type": "bigint" } } ], "desc": "

Resolves a symbol address from a loaded library.

\n

This is equivalent to calling handle.getSymbol(symbol).

" }, { "textRaw": "`ffi.toString(pointer)`", "name": "toString", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" } ], "return": { "textRaw": "Returns: {string | null}", "name": "return", "type": "string | null" } } ], "desc": "

Reads a NUL-terminated UTF-8 string from native memory.

\n

If pointer is 0n, null is returned.

\n

This function does not validate that pointer refers to readable memory or\nthat the pointed-to data is terminated with \\0. Passing an invalid pointer,\na pointer to freed memory, or a pointer to bytes without a terminating NUL can\nread unrelated memory, crash the process, or produce truncated or garbled\noutput.

\n
const { toString } = require('node:ffi');\n\nconst value = toString(ptr);\n
" }, { "textRaw": "`ffi.toBuffer(pointer, length[, copy])`", "name": "toBuffer", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" }, { "textRaw": "`length` {number}", "name": "length", "type": "number" }, { "textRaw": "`copy` {boolean} When `false`, creates a zero-copy view. **Default:** `true`.", "name": "copy", "type": "boolean", "default": "`true`", "desc": "When `false`, creates a zero-copy view.", "optional": true } ], "return": { "textRaw": "Returns: {Buffer}", "name": "return", "type": "Buffer" } } ], "desc": "

Creates a Buffer from native memory.

\n

When copy is true, the returned Buffer owns its own copied memory.\nWhen copy is false, the returned Buffer references the original native\nmemory directly.

\n

Using copy: false is a zero-copy escape hatch. The returned Buffer is a\nwritable view onto foreign memory, so writes in JavaScript update the original\nnative memory directly. The caller must guarantee that:

\n\n

If these guarantees are not met, reading or writing the Buffer can corrupt\nmemory or crash the process.

" }, { "textRaw": "`ffi.toArrayBuffer(pointer, length[, copy])`", "name": "toArrayBuffer", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" }, { "textRaw": "`length` {number}", "name": "length", "type": "number" }, { "textRaw": "`copy` {boolean} When `false`, creates a zero-copy view. **Default:** `true`.", "name": "copy", "type": "boolean", "default": "`true`", "desc": "When `false`, creates a zero-copy view.", "optional": true } ], "return": { "textRaw": "Returns: {ArrayBuffer}", "name": "return", "type": "ArrayBuffer" } } ], "desc": "

Creates an ArrayBuffer from native memory.

\n

When copy is true, the returned ArrayBuffer contains copied bytes.\nWhen copy is false, the returned ArrayBuffer references the original\nnative memory directly.

\n

The same lifetime and bounds requirements described for\nffi.toBuffer(pointer, length, copy) apply\nhere. With copy: false, the\nreturned ArrayBuffer is a zero-copy view of foreign memory and is only safe\nwhile that memory remains allocated, unchanged in layout, and valid for the\nentire exposed range.

" }, { "textRaw": "`ffi.exportString(string, pointer, length[, encoding])`", "name": "exportString", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`string` {string}", "name": "string", "type": "string" }, { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" }, { "textRaw": "`length` {number}", "name": "length", "type": "number" }, { "textRaw": "`encoding` {string} **Default:** `'utf8'`.", "name": "encoding", "type": "string", "default": "`'utf8'`", "optional": true } ] } ], "desc": "

Copies a JavaScript string into native memory and appends a trailing NUL\nterminator.

\n

length must be large enough to hold the full encoded string plus the trailing\nNUL terminator. For UTF-16 and UCS-2 encodings, the trailing terminator uses\ntwo zero bytes.

\n

pointer must refer to writable native memory with at least length bytes of\navailable storage. This function does not allocate memory on its own.

\n

string must be a JavaScript string. encoding must be a string.

" }, { "textRaw": "`ffi.exportBuffer(buffer, pointer, length)`", "name": "exportBuffer", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`buffer` {Buffer}", "name": "buffer", "type": "Buffer" }, { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" }, { "textRaw": "`length` {number}", "name": "length", "type": "number" } ] } ], "desc": "

Copies bytes from a Buffer into native memory.

\n

length must be at least buffer.length.

\n

pointer must refer to writable native memory with at least length bytes of\navailable storage. This function does not allocate memory on its own.

\n

buffer must be a Node.js Buffer.

" }, { "textRaw": "`ffi.exportArrayBuffer(arrayBuffer, pointer, length)`", "name": "exportArrayBuffer", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`arrayBuffer` {ArrayBuffer}", "name": "arrayBuffer", "type": "ArrayBuffer" }, { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" }, { "textRaw": "`length` {number}", "name": "length", "type": "number" } ] } ], "desc": "

Copies bytes from an ArrayBuffer into native memory.

\n

length must be at least arrayBuffer.byteLength.

\n

pointer must refer to writable native memory with at least length bytes of\navailable storage. This function does not allocate memory on its own.

" }, { "textRaw": "`ffi.exportArrayBufferView(arrayBufferView, pointer, length)`", "name": "exportArrayBufferView", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`arrayBufferView` {ArrayBufferView}", "name": "arrayBufferView", "type": "ArrayBufferView" }, { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" }, { "textRaw": "`length` {number}", "name": "length", "type": "number" } ] } ], "desc": "

Copies bytes from an ArrayBufferView into native memory.

\n

length must be at least arrayBufferView.byteLength.

\n

pointer must refer to writable native memory with at least length bytes of\navailable storage. This function does not allocate memory on its own.

" }, { "textRaw": "`ffi.getRawPointer(source)`", "name": "getRawPointer", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`source` {Buffer | ArrayBuffer | SharedArrayBuffer | ArrayBufferView}", "name": "source", "type": "Buffer | ArrayBuffer | SharedArrayBuffer | ArrayBufferView" } ], "return": { "textRaw": "Returns: {bigint}", "name": "return", "type": "bigint" } } ], "desc": "

Returns the raw memory address of JavaScript-managed byte storage.

\n

This is unsafe and dangerous. The returned pointer can become invalid if the\nunderlying memory is detached, resized, transferred, or otherwise invalidated.\nUsing stale pointers can cause memory corruption or process crashes.

" }, { "textRaw": "`ffi.getCurrentEventLoop()`", "name": "getCurrentEventLoop", "type": "method", "meta": { "added": [ "v26.6.0" ], "changes": [] }, "signatures": [ { "params": [], "return": { "textRaw": "Returns: {bigint}", "name": "return", "type": "bigint" } } ], "desc": "

Returns the address of the current thread's uv_loop_t as a bigint.

\n

The returned address is for the current Node.js environment. In the main thread,\nthis is the main thread event loop. In a worker thread, this is that worker's\nevent loop.

\n

This is unsafe and dangerous. The returned pointer is only valid for the lifetime\nof the current environment. Using it after the environment exits, or from native\ncode that assumes a different thread or lifetime, can crash the process or\ncorrupt memory.

" } ], "classes": [ { "textRaw": "Class: `DynamicLibrary`", "name": "DynamicLibrary", "type": "class", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "desc": "

Represents a loaded dynamic library.

", "signatures": [ { "textRaw": "`new DynamicLibrary(path)`", "name": "DynamicLibrary", "type": "ctor", "meta": { "changes": [ { "version": "REPLACEME", "pr-url": "https://github.com/nodejs/node/pull/65909", "description": "Library paths inside a mounted virtual file system are now supported." } ] }, "params": [ { "textRaw": "`path` {string | null} Path to a dynamic library, or `null` to resolve symbols from the current process image.", "name": "path", "type": "string | null", "desc": "Path to a dynamic library, or `null` to resolve symbols from the current process image." } ], "desc": "

Loads the dynamic library without resolving any functions eagerly.

\n

On Windows passing null is not supported.

\n

A path inside a mounted virtual file system loads the same way as\nwith ffi.dlopen().

\n
const { DynamicLibrary, suffix } = require('node:ffi');\n\nconst lib = new DynamicLibrary(`./mylib.${suffix}`);\n
" } ], "properties": [ { "textRaw": "{string}", "name": "path", "type": "string", "desc": "

The path used to load the library.

" }, { "textRaw": "{Object}", "name": "functions", "type": "Object", "desc": "

An object containing previously resolved function wrappers.

" }, { "textRaw": "{Object}", "name": "symbols", "type": "Object", "desc": "

An object containing previously resolved symbol addresses as bigint values.

" } ], "methods": [ { "textRaw": "`library.close()`", "name": "close", "type": "method", "signatures": [ { "params": [] } ], "desc": "

Closes the library handle.

\n

DynamicLibrary implements the explicit resource management protocol, so a\nlibrary instance can be managed with the using declaration. Leaving the\nenclosing scope invokes library.close() automatically.

\n
import { DynamicLibrary, suffix } from 'node:ffi';\n\n{\n  using lib = new DynamicLibrary(`./mylib.${suffix}`);\n  // Use `lib` here; `lib.close()` is called when the block exits.\n}\n
\n

Calling library.close() (or disposing the library) more than once is a no-op.

\n

After a library has been closed:

\n\n

Closing a library does not make previously exported callback pointers safe to\nreuse. Node.js does not track or revoke callback pointers that have already\nbeen handed to native code.

\n

If native code still holds a callback pointer after library.close() or after\nlibrary.unregisterCallback(pointer), invoking that pointer has undefined\nbehavior, is not allowed, and is dangerous: it can crash the process, produce\nincorrect output, or corrupt memory. Native code must stop using callback\naddresses before the library is closed or before the callback is unregistered.

\n

Calling library.close() from one of the library's active callbacks is\nunsupported and dangerous. The callback must return before the library is\nclosed.

" }, { "textRaw": "`library[Symbol.dispose]()`", "name": "[Symbol.dispose]", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "

Calls library.close(). This allows DynamicLibrary instances to be used with\nthe using declaration for automatic cleanup when the enclosing scope\nexits. It is a no-op on a library that has already been closed.

" }, { "textRaw": "`library.getFunction(name, signature)`", "name": "getFunction", "type": "method", "signatures": [ { "params": [ { "textRaw": "`name` {string}", "name": "name", "type": "string" }, { "textRaw": "`signature` {Object}", "name": "signature", "type": "Object" } ], "return": { "textRaw": "Returns: {Function}", "name": "return", "type": "Function" } } ], "desc": "

Resolves a symbol and returns a callable JavaScript wrapper.

\n

The returned function has a .pointer property containing the native function\naddress as a bigint.

\n

If the same symbol has already been resolved, requesting it again with a\ndifferent signature throws. Requesting it again with the same signature returns\nthe same function, as does reading it from library.functions.

\n
const { DynamicLibrary, suffix } = require('node:ffi');\n\nconst lib = new DynamicLibrary(`./mylib.${suffix}`);\nconst add = lib.getFunction('add_i32', {\n  arguments: ['int32', 'int32'],\n  return: 'int32',\n});\n\nconsole.log(add(20, 22));\nconsole.log(add.pointer);\n
" }, { "textRaw": "`library.getFunctions([definitions])`", "name": "getFunctions", "type": "method", "signatures": [ { "params": [ { "textRaw": "`definitions` {Object}", "name": "definitions", "type": "Object", "optional": true } ], "return": { "textRaw": "Returns: {Object}", "name": "return", "type": "Object" } } ], "desc": "

When definitions is provided, resolves each named symbol and returns an\nobject containing callable wrappers.

\n

When definitions is omitted, returns wrappers for all functions that have\nalready been resolved on the library.

" }, { "textRaw": "`library.getSymbol(name)`", "name": "getSymbol", "type": "method", "signatures": [ { "params": [ { "textRaw": "`name` {string}", "name": "name", "type": "string" } ], "return": { "textRaw": "Returns: {bigint}", "name": "return", "type": "bigint" } } ], "desc": "

Resolves a symbol and returns its native address as a bigint.

" }, { "textRaw": "`library.getSymbols()`", "name": "getSymbols", "type": "method", "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Object}", "name": "return", "type": "Object" } } ], "desc": "

Returns an object containing all previously resolved symbol addresses.

" }, { "textRaw": "`library.registerCallback([signature,] callback)`", "name": "registerCallback", "type": "method", "signatures": [ { "params": [ { "textRaw": "`signature` {Object}", "name": "signature", "type": "Object", "optional": true }, { "name": " callback" } ], "return": { "textRaw": "Returns: {bigint}", "name": "return", "type": "bigint" } } ], "desc": "

Creates a native callback pointer backed by a JavaScript function.

\n

When signature is omitted, the callback uses a default void () signature.

\n

The return value is the callback pointer address as a bigint. It can be\npassed to native functions expecting a callback pointer.

\n
const { DynamicLibrary, suffix } = require('node:ffi');\n\nconst lib = new DynamicLibrary(`./mylib.${suffix}`);\n\nconst callback = lib.registerCallback(\n  { arguments: ['int32'], return: 'int32' },\n  (value) => value * 2,\n);\n
\n

Callbacks are subject to the following restrictions:

\n\n

Closing the owning library or unregistering the currently executing callback\nfrom inside the callback is unsupported and dangerous. Doing so may crash the\nprocess, produce incorrect output, or corrupt memory.

" }, { "textRaw": "`library.unregisterCallback(pointer)`", "name": "unregisterCallback", "type": "method", "signatures": [ { "params": [ { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" } ] } ], "desc": "

Releases a callback previously created with library.registerCallback().

\n

Calling library.unregisterCallback(pointer) for a callback that is currently\nexecuting is unsupported and dangerous. The callback must return before it is\nunregistered.

\n

After library.unregisterCallback(pointer) returns, invoking that callback\npointer from native code has undefined behavior, is not allowed, and is\ndangerous: it can crash the process, produce incorrect output, or corrupt\nmemory.

" }, { "textRaw": "`library.refCallback(pointer)`", "name": "refCallback", "type": "method", "signatures": [ { "params": [ { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" } ] } ], "desc": "

Keeps the callback strongly referenced by JavaScript.

\n

Throws ERR_INVALID_ARG_VALUE if the callback function has already been\ngarbage collected after a previous library.unrefCallback(pointer) call, since\na collected function cannot be referenced again.

" }, { "textRaw": "`library.unrefCallback(pointer)`", "name": "unrefCallback", "type": "method", "signatures": [ { "params": [ { "textRaw": "`pointer` {bigint}", "name": "pointer", "type": "bigint" } ] } ], "desc": "

Allows the callback to become weakly referenced by JavaScript.

\n

If the callback function is later garbage collected, subsequent native\ninvocations become a no-op. Non-void return values are zero-initialized before\nreturning to native code.

\n

Throws ERR_INVALID_ARG_VALUE if the callback function has already been\ngarbage collected.

" } ] } ], "displayName": "FFI" } ] }