{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"ffi","path":"/ffi","type":"module","module":"ffi","title":"FFI","introducedIn":"v26.1.0","sourceLink":{"path":"lib/ffi.js","url":"https://github.com/nodejs/node/blob/HEAD/lib/ffi.js"},"stability":{"index":"1","description":"Experimental"},"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `node:ffi` module provides an experimental foreign function interface for\nloading dynamic libraries and calling native symbols from JavaScript.\n\nThis 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\nTo access it:\n\n```mjs\nimport ffi from 'node:ffi';\n```\n\n```cjs\nconst ffi = require('node:ffi');\n```\n\nThis module is only available under the `node:` scheme in builds with FFI\nsupport. It can be disabled with the `--no-experimental-ffi` flag.\n\nBuilding 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\nThe following targets are not supported by bundled libffi:\n\n* `s390x`.\n* `mips`, `mipsel`, and `mips64el` on targets other than FreeBSD, Linux, and\n  OpenBSD.\n* `ppc64` on Android, CloudABI, iOS, OpenHarmony, OS/400, Solaris, and Windows.\n\nWhen using the [Permission Model](permissions.html#permission-model), FFI APIs are\nrestricted unless the [`--allow-ffi`](cli.html#--allow-ffi) flag is provided.","summary":"The `node:ffi` module provides an experimental foreign function interface for loading dynamic libraries and calling native symbols from JavaScript.","examples":[{"language":"mjs","displayName":null,"code":"import ffi from 'node:ffi';"},{"language":"cjs","displayName":null,"code":"const ffi = require('node:ffi');"}],"children":[{"kind":"section","id":"overview","name":"Overview","title":"Overview","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `node:ffi` module exposes two groups of APIs:\n\n* Dynamic library APIs for loading libraries, resolving symbols, and creating\n  callable JavaScript wrappers.\n* Raw memory helpers for reading and writing primitive values through pointers,\n  converting pointers to JavaScript strings, `Buffer` instances, and\n  `ArrayBuffer` instances, and for copying data back into native memory.","summary":"The `node:ffi` module exposes two groups of APIs:","examples":[],"children":[]},{"kind":"section","id":"type-names","name":"Type names","title":"Type names","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"FFI signatures use string type names.\n\nSupported type names:\n\n* `void`\n* `char`\n* `int8`\n* `uint8`\n* `int16`\n* `uint16`\n* `int32`\n* `uint32`\n* `int64`\n* `uint64`\n* `float32`\n* `float64`\n* `pointer`\n* `string`\n* `buffer`\n* `arraybuffer`\n* `function`\n\n<details>\n<summary>Alternative spellings</summary>\n\n* `i8` for `int8`\n* `u8` and `bool` for `uint8`\n* `i16` for `int16`\n* `u16` for `uint16`\n* `i32` for `int32`\n* `u32` for `uint32`\n* `i64` for `int64`\n* `u64` for `uint64`\n* `f32` and `float` for `float32`\n* `f64` and `double` for `float64`\n* `ptr` for `pointer`\n* `str` for `string`\n\n</details>\n\nThese type names are also exposed as constants on `ffi.types`:\n\n* `ffi.types.VOID` = `'void'`\n* `ffi.types.POINTER` = `'pointer'`\n* `ffi.types.BUFFER` = `'buffer'`\n* `ffi.types.ARRAY_BUFFER` = `'arraybuffer'`\n* `ffi.types.FUNCTION` = `'function'`\n* `ffi.types.BOOL` = `'bool'`\n* `ffi.types.CHAR` = `'char'`\n* `ffi.types.STRING` = `'string'`\n* `ffi.types.FLOAT` = `'float'`\n* `ffi.types.DOUBLE` = `'double'`\n* `ffi.types.INT_8` = `'int8'`\n* `ffi.types.UINT_8` = `'uint8'`\n* `ffi.types.INT_16` = `'int16'`\n* `ffi.types.UINT_16` = `'uint16'`\n* `ffi.types.INT_32` = `'int32'`\n* `ffi.types.UINT_32` = `'uint32'`\n* `ffi.types.INT_64` = `'int64'`\n* `ffi.types.UINT_64` = `'uint64'`\n* `ffi.types.FLOAT_32` = `'float32'`\n* `ffi.types.FLOAT_64` = `'float64'`\n\nPointer-like types (`pointer`, `string`, `buffer`, `arraybuffer`, and\n`function`) are all passed through the native layer as pointers.\n\nWhen `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\nIt 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\nThe `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\nThe `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\nOn 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\nOptimized Fast FFI calls fall back to another [call path](#call-paths) 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| Architecture               | Max integer/pointer args                  | Max floating-point args | Buffer-shaped args | Buffer-shaped + FP together | Narrow (8/16-bit) return |\n| -------------------------- | ----------------------------------------- | ----------------------- | ------------------ | --------------------------- | ------------------------ |\n| AArch64                    | 7 (6 when a buffer-shaped arg is present) | 8                       | Supported          | Not supported               | Supported                |\n| x86-64, Linux/macOS (SysV) | 6 (4 when a buffer-shaped arg is present) | 8                       | Supported          | Not supported               | Supported                |\n| x86-64, Windows (Win64)    | 3 (total arguments also capped at 3)      | 3                       | Not supported      | N/A                         | Supported                |\n| s390x                      | 4                                         | 4                       | Not supported      | N/A                         | Not supported            |\n| PPC64LE                    | 7                                         | 8                       | Not supported      | N/A                         | Not supported            |\n| LoongArch64                | 7                                         | 8                       | Not supported      | N/A                         | Not supported            |\n| RISC-V (64-bit)            | 7                                         | 8                       | Not supported      | N/A                         | Not supported            |\n\nPPC64BE 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\n[call paths](#call-paths) instead.","summary":"FFI signatures use string type names.","examples":[],"children":[]},{"kind":"section","id":"signature-objects","name":"Signature objects","title":"Signature objects","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Functions and callbacks are described with signature objects.\n\nSignature objects may contain the following properties, both of which are\noptional:\n\n* `return` {string} A [type name](#type-names) specifying the return type of the\n  function or callback. **Default:** `'void'`.\n* `arguments` {string[]} An array of [type names](#type-names) specifying the argument\n  type list of the function or callback. **Default:** `[]`.\n\n```js\nconst signature = {\n  return: 'int32',\n  arguments: ['int32', 'int32'],\n};\n```","summary":"Functions and callbacks are described with signature objects.","examples":[{"language":"js","displayName":null,"code":"const signature = {\n  return: 'int32',\n  arguments: ['int32', 'int32'],\n};"}],"children":[]},{"kind":"property","id":"ffisuffix","name":"suffix","title":"`ffi.suffix`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"default":null,"description":"The native shared library suffix for the current platform:\n\n* `'dylib'` on macOS\n* `'so'` on Unix-like platforms\n* `'dll'` on Windows\n\nThis can be used to build portable library paths:\n\n```cjs\nconst { suffix } = require('node:ffi');\n\nconst path = `libsqlite3.${suffix}`;\n```","summary":"The native shared library suffix for the current platform:","examples":[{"language":"cjs","displayName":null,"code":"const { suffix } = require('node:ffi');\n\nconst path = `libsqlite3.${suffix}`;"}],"children":[]},{"kind":"method","id":"ffidlopenpath-definitions","name":"dlopen","title":"`ffi.dlopen(path[, definitions])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[{"versions":["v26.10.0"],"prUrl":"https://github.com/nodejs/node/pull/65909","commit":null,"description":"Library paths inside a mounted virtual file system are now supported."}],"signature":{"parameters":[{"name":"path","type":{"text":"string | null","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"null","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#null_type","start":9,"end":13}]},"description":"Path to a dynamic library, or `null` to resolve symbols\nfrom the current process image.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"definitions","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"Symbol definitions to resolve immediately.","default":null,"optional":true,"rest":false,"properties":[]}],"returns":{"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":""}},"description":"Loads a dynamic library and resolves the requested function definitions.\n\nOn Windows passing `null` is not supported.\n\nA `path` inside a mounted [virtual file system](vfs.html) 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\nWhen `definitions` is omitted, `functions` is returned as an empty object until\nsymbols are resolved explicitly.\n\nThe returned object contains:\n\n* `lib` {DynamicLibrary} The loaded library handle.\n* `functions` {Object} Callable wrappers for the requested symbols.\n\nThe returned object also implements the explicit resource management protocol,\nso it can be used with the [`using`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using) declaration. Disposing the returned\nobject closes the library handle.\n\n```mjs\nimport { 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\n```mjs\nimport { 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\n```cjs\nconst { 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```","summary":"Loads a dynamic library and resolves the requested function definitions.","examples":[{"language":"mjs","displayName":null,"code":"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."},{"language":"mjs","displayName":null,"code":"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));"},{"language":"cjs","displayName":null,"code":"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));"}],"children":[]},{"kind":"method","id":"ffidlclosehandle","name":"dlclose","title":"`ffi.dlclose(handle)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"handle","type":{"text":"DynamicLibrary","links":[{"name":"DynamicLibrary","href":"ffi.html#class-dynamiclibrary","start":0,"end":14}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Closes a dynamic library.\n\nThis is equivalent to calling `handle.close()`.","summary":"Closes a dynamic library.","examples":[],"children":[]},{"kind":"method","id":"ffidlsymhandle-symbol","name":"dlsym","title":"`ffi.dlsym(handle, symbol)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"handle","type":{"text":"DynamicLibrary","links":[{"name":"DynamicLibrary","href":"ffi.html#class-dynamiclibrary","start":0,"end":14}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"symbol","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":""}},"description":"Resolves a symbol address from a loaded library.\n\nThis is equivalent to calling `handle.getSymbol(symbol)`.","summary":"Resolves a symbol address from a loaded library.","examples":[],"children":[]},{"kind":"class","id":"class-dynamiclibrary","name":"DynamicLibrary","title":"Class: `DynamicLibrary`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"Represents a loaded dynamic library.","summary":"Represents a loaded dynamic library.","examples":[],"children":[{"kind":"constructor","id":"new-dynamiclibrarypath","name":"DynamicLibrary","title":"`new DynamicLibrary(path)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[{"versions":["v26.10.0"],"prUrl":"https://github.com/nodejs/node/pull/65909","commit":null,"description":"Library paths inside a mounted virtual file system are now supported."}],"signature":{"parameters":[{"name":"path","type":{"text":"string | null","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"null","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#null_type","start":9,"end":13}]},"description":"Path to a dynamic library, or `null` to resolve symbols\nfrom the current process image.","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Loads the dynamic library without resolving any functions eagerly.\n\nOn Windows passing `null` is not supported.\n\nA `path` inside a mounted [virtual file system](vfs.html) loads the same way as\nwith [`ffi.dlopen()`](#ffidlopenpath-definitions).\n\n```cjs\nconst { DynamicLibrary, suffix } = require('node:ffi');\n\nconst lib = new DynamicLibrary(`./mylib.${suffix}`);\n```","summary":"Loads the dynamic library without resolving any functions eagerly.","examples":[{"language":"cjs","displayName":null,"code":"const { DynamicLibrary, suffix } = require('node:ffi');\n\nconst lib = new DynamicLibrary(`./mylib.${suffix}`);"}],"children":[]},{"kind":"property","id":"librarypath","name":"path","title":"`library.path`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"default":null,"description":"The path used to load the library.","summary":"The path used to load the library.","examples":[],"children":[]},{"kind":"property","id":"libraryfunctions","name":"functions","title":"`library.functions`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"default":null,"description":"An object containing previously resolved function wrappers.","summary":"An object containing previously resolved function wrappers.","examples":[],"children":[]},{"kind":"property","id":"librarysymbols","name":"symbols","title":"`library.symbols`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"default":null,"description":"An object containing previously resolved symbol addresses as `bigint` values.","summary":"An object containing previously resolved symbol addresses as `bigint` values.","examples":[],"children":[]},{"kind":"method","id":"libraryclose","name":"close","title":"`library.close()`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"Closes the library handle.\n\n`DynamicLibrary` implements the explicit resource management protocol, so a\nlibrary instance can be managed with the [`using`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using) declaration. Leaving the\nenclosing scope invokes `library.close()` automatically.\n\n```mjs\nimport { 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\nCalling `library.close()` (or disposing the library) more than once is a no-op.\n\nAfter a library has been closed:\n\n* Resolved function wrappers become invalid.\n* Further symbol and function resolution throws.\n* Registered callbacks are invalidated.\n\nClosing 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\nIf native code still holds a callback pointer after `library.close()` or after\n`library.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\nCalling `library.close()` from one of the library's active callbacks is\nunsupported and dangerous. The callback must return before the library is\nclosed.","summary":"Closes the library handle.","examples":[{"language":"mjs","displayName":null,"code":"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}"}],"children":[]},{"kind":"method","id":"librarysymboldispose","name":"[Symbol.dispose]","title":"`library[Symbol.dispose]()`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"Calls `library.close()`. This allows `DynamicLibrary` instances to be used with\nthe [`using`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using) declaration for automatic cleanup when the enclosing scope\nexits. It is a no-op on a library that has already been closed.","summary":"Calls `library.close()`. This allows `DynamicLibrary` instances to be used with the `using` declaration for automatic cleanup when the enclosing scope exits. It is a no-op on a library that has already been closed.","examples":[],"children":[]},{"kind":"method","id":"librarygetfunctionname-signature","name":"getFunction","title":"`library.getFunction(name, signature)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"name","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"signature","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"description":""}},"description":"Resolves a symbol and returns a callable JavaScript wrapper.\n\nThe returned function has a `.pointer` property containing the native function\naddress as a `bigint`.\n\nIf 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`](#libraryfunctions).\n\n```cjs\nconst { 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```","summary":"Resolves a symbol and returns a callable JavaScript wrapper.","examples":[{"language":"cjs","displayName":null,"code":"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);"}],"children":[]},{"kind":"method","id":"librarygetfunctionsdefinitions","name":"getFunctions","title":"`library.getFunctions([definitions])`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"definitions","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":true,"rest":false,"properties":[]}],"returns":{"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":""}},"description":"When `definitions` is provided, resolves each named symbol and returns an\nobject containing callable wrappers.\n\nWhen `definitions` is omitted, returns wrappers for all functions that have\nalready been resolved on the library.","summary":"When `definitions` is provided, resolves each named symbol and returns an object containing callable wrappers.","examples":[],"children":[]},{"kind":"method","id":"librarygetsymbolname","name":"getSymbol","title":"`library.getSymbol(name)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"name","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":""}},"description":"Resolves a symbol and returns its native address as a `bigint`.","summary":"Resolves a symbol and returns its native address as a `bigint`.","examples":[],"children":[]},{"kind":"method","id":"librarygetsymbols","name":"getSymbols","title":"`library.getSymbols()`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":{"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":""}},"description":"Returns an object containing all previously resolved symbol addresses.","summary":"Returns an object containing all previously resolved symbol addresses.","examples":[],"children":[]},{"kind":"method","id":"libraryregistercallbacksignature-callback","name":"registerCallback","title":"`library.registerCallback([signature,] callback)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"signature","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":true,"rest":false,"properties":[]},{"name":" callback","type":null,"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":""}},"description":"Creates a native callback pointer backed by a JavaScript function.\n\nWhen `signature` is omitted, the callback uses a default `void ()` signature.\n\nThe return value is the callback pointer address as a `bigint`. It can be\npassed to native functions expecting a callback pointer.\n\n```cjs\nconst { 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\nCallbacks are subject to the following restrictions:\n\n* They must be invoked on the same system thread where they were created.\n* They must not throw exceptions.\n* They must not return promises.\n* They must return a value compatible with the declared return type.\n* They must not call `library.close()` on their owning library while running.\n* They must not unregister themselves while running.\n\nClosing 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.\n\nIf the thread running a callback is stopped while the callback executes, for\nexample by `worker.terminate()`, by `process.exit()` in a Worker, or by the\nmain thread exiting, only that thread stops. The callback returns to native\ncode without a value: non-void return values are zero-initialized, so native\ncode receives `0`, `false`, or a null pointer. Native code that does not\nhandle such a value, for example by dereferencing a returned null pointer, can\ncrash the process.","summary":"Creates a native callback pointer backed by a JavaScript function.","examples":[{"language":"cjs","displayName":null,"code":"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);"}],"children":[]},{"kind":"method","id":"libraryunregistercallbackpointer","name":"unregisterCallback","title":"`library.unregisterCallback(pointer)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Releases a callback previously created with `library.registerCallback()`.\n\nCalling `library.unregisterCallback(pointer)` for a callback that is currently\nexecuting is unsupported and dangerous. The callback must return before it is\nunregistered.\n\nAfter `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.","summary":"Releases a callback previously created with `library.registerCallback()`.","examples":[],"children":[]},{"kind":"method","id":"libraryrefcallbackpointer","name":"refCallback","title":"`library.refCallback(pointer)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Keeps the callback strongly referenced by JavaScript.\n\nThrows `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.","summary":"Keeps the callback strongly referenced by JavaScript.","examples":[],"children":[]},{"kind":"method","id":"libraryunrefcallbackpointer","name":"unrefCallback","title":"`library.unrefCallback(pointer)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Allows the callback to become weakly referenced by JavaScript.\n\nIf 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\nThrows `ERR_INVALID_ARG_VALUE` if the callback function has already been\ngarbage collected.","summary":"Allows the callback to become weakly referenced by JavaScript.","examples":[],"children":[]}]},{"kind":"section","id":"calling-native-functions","name":"Calling native functions","title":"Calling native functions","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Argument conversion depends on the declared FFI type.\n\nFor 8-, 16-, and 32-bit integer types and for floating-point types, pass\nJavaScript `number` values that match the declared type.\n\nFor 64-bit integer types (`int64` and `uint64`), pass JavaScript `bigint`\nvalues within the declared type's range or safe integer `number` values.\nFor `int64`, numbers must be between `Number.MIN_SAFE_INTEGER` and\n`Number.MAX_SAFE_INTEGER`, inclusive. For `uint64`, numbers must be between\n`0` and `Number.MAX_SAFE_INTEGER`, inclusive. This allows buffer lengths such\nas `buffer.byteLength` to be passed without an explicit `BigInt()` conversion.\nUse `bigint` for integers outside JavaScript's safe integer range.\n\nInvalid arguments, including fractional numbers, `NaN`, infinities, and values\noutside these ranges, throw `ERR_INVALID_ARG_VALUE`. Return values for 64-bit\ninteger types are always exposed as `bigint` values.\n\nFor pointer-like arguments:\n\n* `null` and `undefined` are passed as null pointers.\n* `string` values are copied to temporary NUL-terminated UTF-8 strings for the\n  duration of the call.\n* `Buffer`, typed arrays, and `DataView` instances pass a pointer to their\n  backing memory.\n* `ArrayBuffer` passes a pointer to its backing memory.\n* `bigint` values are passed as raw pointer addresses.\n\nPointer return values are exposed as `bigint` addresses.","summary":"Argument conversion depends on the declared FFI type.","examples":[],"children":[]},{"kind":"section","id":"call-paths","name":"Call paths","title":"Call paths","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"When a symbol is resolved through [`ffi.dlopen()`](#ffidlopenpath-definitions),\n[`library.getFunction()`](#librarygetfunctionname-signature), or [`library.getFunctions()`](#librarygetfunctionsdefinitions), 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\nThe call paths are designed to accept the same JavaScript values for each\n[type name](#type-names), 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\nNode.js tries the call paths in the following order and uses the first one that\nsupports the signature:\n\n1. The [Fast API call path](#fast-api-call-path), which lets optimized JavaScript call the native\n   symbol directly through a generated per-signature trampoline.\n2. The [shared buffer call path](#shared-buffer-call-path), which passes arguments through a\n   preallocated buffer instead of converting each argument across the\n   JavaScript and C++ boundary on every call.\n3. The [generic call path](#generic-call-path), which converts each argument in C++ and calls the\n   symbol through `libffi`. This path supports every signature.\n\nThe contributor guide [FFI Fast API internals](https://github.com/nodejs/node/blob/HEAD/doc/contributing/ffi-fast-api-internals.md) describes the implementation of\nthese call paths in detail.","summary":"When a symbol is resolved through `ffi.dlopen()`, `library.getFunction()`, or `library.getFunctions()`, Node.js selects one of three native call paths for the returned wrapper. The selection is based on the declared signature, on the current platform, and on the capabilities of the current process. It is made once when the function is created, cannot be configured, and is not observable from JavaScript.","examples":[],"children":[{"kind":"section","id":"fast-api-call-path","name":"Fast API call path","title":"Fast API call path","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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\nFunctions 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](#generic-call-path). This is transparent to the\ncaller.\n\nPointer-like arguments are prepared in JavaScript before the trampoline runs:\n\n* `null` and `undefined` become null pointers.\n* `string` values are copied into temporary NUL-terminated UTF-8 buffers for\n  the duration of the call.\n* `Buffer`, typed array, `DataView`, and `ArrayBuffer` values are converted to\n  raw pointer `bigint` values, unless the alternate entry point described below\n  handles them.\n* `bigint` values are passed through unchanged.\n\nFor 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\nA function uses this call path only when all of the following conditions are\nmet:\n\n* The process runs on a supported 64-bit architecture: AArch64, x86-64,\n  PPC64LE, LoongArch64, RISC-V 64, or s390x. 32-bit platforms and big-endian\n  PPC64 always use another call path.\n* The process can allocate executable memory. Node.js checks once per process\n  whether it can allocate memory and mark it executable. If that check fails,\n  this path is disabled for the entire process.\n* Neither the return type nor any argument type is `function`.\n* The signature has at most 8 arguments, and every argument fits in the\n  argument registers available to the trampoline on the current platform.\n  Arguments that would have to be passed on the native stack are not supported.\n\nThe 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](#type-names).\n\nA signature that fails any of these checks is not an error. The function is\ncreated on the next call path that supports it.","summary":"The Fast API call path binds the wrapper as a V8 Fast API function. When JavaScript code calling the wrapper is optimized by V8, the call goes from the optimized code straight into a small native trampoline that Node.js generates for the exact signature when the function is created. The trampoline moves the arguments into the registers expected by the native symbol and calls it. For the scalar entry point, there is no intermediate argument conversion in C++.","examples":[],"children":[]},{"kind":"section","id":"shared-buffer-call-path","name":"Shared buffer call path","title":"Shared buffer call path","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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\n`libffi` 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\nA function uses this call path when all of the following conditions are met:\n\n* The Fast API call path is not available for the signature.\n* The host is little-endian.\n* The signature has at least one argument. Zero-argument functions gain nothing\n  from the shared buffer and use another call path instead.\n\nAll type names are supported on this path, and there is no limit on the number\nof arguments.\n\nPointer-like arguments (`pointer`, `string`, `buffer`, `arraybuffer`, and\n`function`) are written to the shared buffer only when the value is a `bigint`,\n`null`, or `undefined`. When a call passes a string, `Buffer`, typed array,\n`DataView`, or `ArrayBuffer` to a pointer-like parameter, that individual call\nis handed off to the [generic call path](#generic-call-path), which performs the conversion in\nC++. The function itself stays on the shared buffer call path for later calls.\n\nThe 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.","summary":"The shared buffer call path is used for signatures that the Fast API call path does not support. When the function is created, Node.js allocates a small per-function buffer with one 8-byte slot for the return value and one 8-byte slot for each argument. On every call, the JavaScript wrapper validates the arguments, writes them into their slots, invokes the native symbol through `libffi` without passing any JavaScript arguments, and then reads the return value back from the buffer. This avoids converting each argument individually across the JavaScript and C++ boundary.","examples":[],"children":[]},{"kind":"section","id":"generic-call-path","name":"Generic call path","title":"Generic call path","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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\nA 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\nThe 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\nCallbacks created with [`library.registerCallback()`](#libraryregistercallbacksignature-callback) are always implemented\nwith `libffi` closures. They are independent of the call path used by any\nfunction.","summary":"The generic call path converts each JavaScript argument to its native representation in C++ and calls the symbol through `libffi`. It supports every signature that `node:ffi` accepts and is the reference implementation for the argument validation and error behavior that the other call paths reproduce.","examples":[],"children":[]}]},{"kind":"section","id":"primitive-memory-access-helpers","name":"Primitive memory access helpers","title":"Primitive memory access helpers","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The following helpers read and write primitive values at a native pointer,\noptionally with a byte offset:\n\n* `ffi.getInt8(pointer[, offset])`\n* `ffi.getUint8(pointer[, offset])`\n* `ffi.getInt16(pointer[, offset])`\n* `ffi.getUint16(pointer[, offset])`\n* `ffi.getInt32(pointer[, offset])`\n* `ffi.getUint32(pointer[, offset])`\n* `ffi.getInt64(pointer[, offset])`\n* `ffi.getUint64(pointer[, offset])`\n* `ffi.getFloat32(pointer[, offset])`\n* `ffi.getFloat64(pointer[, offset])`\n* `ffi.setInt8(pointer, offset, value)`\n* `ffi.setUint8(pointer, offset, value)`\n* `ffi.setInt16(pointer, offset, value)`\n* `ffi.setUint16(pointer, offset, value)`\n* `ffi.setInt32(pointer, offset, value)`\n* `ffi.setUint32(pointer, offset, value)`\n* `ffi.setInt64(pointer, offset, value)`\n* `ffi.setUint64(pointer, offset, value)`\n* `ffi.setFloat32(pointer, offset, value)`\n* `ffi.setFloat64(pointer, offset, value)`\n\nThese helpers perform direct memory reads and writes. `pointer` must be a\n`bigint` referring to valid readable or writable native memory. `offset`, when\nprovided, is interpreted as a byte offset from `pointer`.\n\nThe 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\nThe 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\n```cjs\nconst {\n  getInt32,\n  setInt32,\n} = require('node:ffi');\n\nsetInt32(ptr, 0, 42);\nconsole.log(getInt32(ptr, 0));\n```\n\nLike 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.","summary":"The following helpers read and write primitive values at a native pointer, optionally with a byte offset:","examples":[{"language":"cjs","displayName":null,"code":"const {\n  getInt32,\n  setInt32,\n} = require('node:ffi');\n\nsetInt32(ptr, 0, 42);\nconsole.log(getInt32(ptr, 0));"}],"children":[]},{"kind":"method","id":"ffitostringpointer","name":"toString","title":"`ffi.toString(pointer)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"string | null","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"null","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#null_type","start":9,"end":13}]},"description":""}},"description":"Reads a NUL-terminated UTF-8 string from native memory.\n\nIf `pointer` is `0n`, `null` is returned.\n\nThis 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\n```cjs\nconst { toString } = require('node:ffi');\n\nconst value = toString(ptr);\n```","summary":"Reads a NUL-terminated UTF-8 string from native memory.","examples":[{"language":"cjs","displayName":null,"code":"const { toString } = require('node:ffi');\n\nconst value = toString(ptr);"}],"children":[]},{"kind":"method","id":"ffitobufferpointer-length-copy","name":"toBuffer","title":"`ffi.toBuffer(pointer, length[, copy])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"length","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"copy","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"When `false`, creates a zero-copy view.","default":"true","optional":true,"rest":false,"properties":[]}],"returns":{"type":{"text":"Buffer","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6}]},"description":""}},"description":"Creates a `Buffer` from native memory.\n\nWhen `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\nUsing `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* `pointer` remains valid for the entire lifetime of the returned `Buffer`.\n* `length` stays within the allocated native region.\n* no native code frees or repurposes that memory while JavaScript still uses\n  the `Buffer`.\n* Memory protection is observed. For example, read-only memory pages must not\n  be written to.\n\nIf these guarantees are not met, reading or writing the `Buffer` can corrupt\nmemory or crash the process.","summary":"Creates a `Buffer` from native memory.","examples":[],"children":[]},{"kind":"method","id":"ffitoarraybufferpointer-length-copy","name":"toArrayBuffer","title":"`ffi.toArrayBuffer(pointer, length[, copy])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"length","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"copy","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"When `false`, creates a zero-copy view.","default":"true","optional":true,"rest":false,"properties":[]}],"returns":{"type":{"text":"ArrayBuffer","links":[{"name":"ArrayBuffer","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer","start":0,"end":11}]},"description":""}},"description":"Creates an `ArrayBuffer` from native memory.\n\nWhen `copy` is `true`, the returned `ArrayBuffer` contains copied bytes.\nWhen `copy` is `false`, the returned `ArrayBuffer` references the original\nnative memory directly.\n\nThe same lifetime and bounds requirements described for\n[`ffi.toBuffer(pointer, length, copy)`](#ffitobufferpointer-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.","summary":"Creates an `ArrayBuffer` from native memory.","examples":[],"children":[]},{"kind":"method","id":"ffiexportstringstring-pointer-length-encoding","name":"exportString","title":"`ffi.exportString(string, pointer, length[, encoding])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"string","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"length","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"encoding","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"","default":"'utf8'","optional":true,"rest":false,"properties":[]}],"returns":null},"description":"Copies a JavaScript string into native memory and appends a trailing NUL\nterminator.\n\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\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\n`string` must be a JavaScript string. `encoding` must be a string.","summary":"Copies a JavaScript string into native memory and appends a trailing NUL terminator.","examples":[],"children":[]},{"kind":"method","id":"ffiexportbufferbuffer-pointer-length","name":"exportBuffer","title":"`ffi.exportBuffer(buffer, pointer, length)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"buffer","type":{"text":"Buffer","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"length","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Copies bytes from a `Buffer` into native memory.\n\n`length` must be at least `buffer.length`.\n\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\n`buffer` must be a Node.js `Buffer`.","summary":"Copies bytes from a `Buffer` into native memory.","examples":[],"children":[]},{"kind":"method","id":"ffiexportarraybufferarraybuffer-pointer-length","name":"exportArrayBuffer","title":"`ffi.exportArrayBuffer(arrayBuffer, pointer, length)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"arrayBuffer","type":{"text":"ArrayBuffer","links":[{"name":"ArrayBuffer","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer","start":0,"end":11}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"length","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Copies bytes from an `ArrayBuffer` into native memory.\n\n`length` must be at least `arrayBuffer.byteLength`.\n\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.","summary":"Copies bytes from an `ArrayBuffer` into native memory.","examples":[],"children":[]},{"kind":"method","id":"ffiexportarraybufferviewarraybufferview-pointer-length","name":"exportArrayBufferView","title":"`ffi.exportArrayBufferView(arrayBufferView, pointer, length)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"arrayBufferView","type":{"text":"ArrayBufferView","links":[{"name":"ArrayBufferView","href":"https://developer.mozilla.org/docs/Web/API/ArrayBufferView","start":0,"end":15}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"pointer","type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]},{"name":"length","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"Copies bytes from an `ArrayBufferView` into native memory.\n\n`length` must be at least `arrayBufferView.byteLength`.\n\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.","summary":"Copies bytes from an `ArrayBufferView` into native memory.","examples":[],"children":[]},{"kind":"method","id":"ffigetrawpointersource","name":"getRawPointer","title":"`ffi.getRawPointer(source)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.1.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"source","type":{"text":"Buffer | ArrayBuffer | SharedArrayBuffer | ArrayBufferView","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6},{"name":"ArrayBuffer","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer","start":9,"end":20},{"name":"SharedArrayBuffer","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer","start":23,"end":40},{"name":"ArrayBufferView","href":"https://developer.mozilla.org/docs/Web/API/ArrayBufferView","start":43,"end":58}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":""}},"description":"Returns the raw memory address of JavaScript-managed byte storage.\n\nThis 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.","summary":"Returns the raw memory address of JavaScript-managed byte storage.","examples":[],"children":[]},{"kind":"method","id":"ffigetcurrenteventloop","name":"getCurrentEventLoop","title":"`ffi.getCurrentEventLoop()`","scope":"module","overloadOf":null,"stability":null,"added":["v26.6.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":{"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"description":""}},"description":"Returns the address of the current thread's `uv_loop_t` as a `bigint`.\n\nThe 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\nThis 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.","summary":"Returns the address of the current thread's `uv_loop_t` as a `bigint`.","examples":[],"children":[]},{"kind":"section","id":"safety-notes","name":"Safety notes","title":"Safety notes","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `node:ffi` module does not track pointer validity, memory ownership, or\nnative object lifetimes.\n\nIn particular:\n\n* Do not read from or write to freed memory.\n* Do not use zero-copy views after the native memory has been released.\n* Do not declare incorrect signatures for native symbols.\n* Do not unregister callbacks while native code may still call them.\n* Do not call callback pointers after `library.close()` or\n  `library.unregisterCallback(pointer)`.\n* Assume undefined callback behavior can crash the process, produce incorrect\n  output, or corrupt memory.\n* Do not assume pointer return values imply ownership; whether the caller must\n  free the returned address depends entirely on the native API.\n\nAs a general rule, prefer copied values unless zero-copy access is required,\nand keep callback and pointer lifetimes explicit on the native side.","summary":"The `node:ffi` module does not track pointer validity, memory ownership, or native object lifetimes.","examples":[],"children":[]}]}