Ende.dlopen

function · requires --allow-ffi

function Ende.dlopen<S extends ForeignLibraryInterface>(filename: string | URL, symbols: S): DynamicLibrary<S>

Opens an external dynamic library and registers symbols, making foreign functions available to be called.

Requires allow-ffi permission. Loading foreign dynamic libraries can in theory bypass all of the sandbox permissions. While it is a separate permission users should acknowledge in practice that is effectively the same as running with the allow-all permission.

Example: Given a C library which exports a foreign function named add()

// Determine library extension based on
// your OS.
let libSuffix = "";
switch (Ende.build.os) {
  case "windows":
    libSuffix = "dll";
    break;
  case "darwin":
    libSuffix = "dylib";
    break;
  default:
    libSuffix = "so";
    break;
}

const libName = `./libadd.${libSuffix}`;
// Open library and define exported symbols
const dylib = Ende.dlopen(
  libName,
  {
    "add": { parameters: ["isize", "isize"], result: "isize" },
  } as const,
);

// Call the symbol `add`
const result = dylib.symbols.add(35n, 34n); // 69n

console.log(`Result from external addition of 35 and 34: ${result}`);