ffi.dlopen

History

ffi.dlopen(path, definitions?): Object

Attributes

path:string | null

Path to a dynamic library, or null to resolve symbols from the current process image.

definitions:Object

Symbol definitions to resolve immediately.

Returns:Object

Loads a dynamic library and resolves the requested function definitions.

On Windows passing null is not supported.

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

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

The returned object contains:

Attributes

lib:DynamicLibrary

The loaded library handle.

functions:Object

Callable wrappers for the requested symbols.

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

import { dlopen, suffix } from 'node:ffi';

{
  using handle = dlopen(`./mylib.${suffix}`, {
    add_i32: { arguments: ['int32', 'int32'], return: 'int32' },
  });
  console.log(handle.functions.add_i32(20, 22));
} // handle.lib.close() is invoked automatically here.

JavaScript

import { dlopen, suffix } from 'node:ffi';

const { lib, functions } = dlopen(`./mylib.${suffix}`, {
  add_i32: { arguments: ['int32', 'int32'], return: 'int32' },
  string_length: { arguments: ['pointer'], return: 'uint64' },
});

console.log(functions.add_i32(20, 22));

JavaScript

const { dlopen, suffix } = require('node:ffi');

const { lib, functions } = dlopen(`./mylib.${suffix}`, {
  add_i32: { arguments: ['int32', 'int32'], return: 'int32' },
  string_length: { arguments: ['pointer'], return: 'uint64' },
});

console.log(functions.add_i32(20, 22));

JavaScript