function

ffi.CFunction

fn: FFIFunction & { ptr: number | bigint | Pointer }

): CallableFunction & { close(): void };

Turn a native library's function pointer into a JavaScript function

Libraries using Node-API & bun:ffi in the same module could use this to skip an extra dlopen() step.

@param fn

FFIFunction declaration. ptr is required

import {CFunction} from 'bun:ffi';

const getVersion = new CFunction({
  returns: "cstring",
  args: [],
  ptr: myNativeLibraryGetVersion,
});
getVersion();
getVersion.close();

Referenced types

interface FFIFunction

readonly args?: readonly FFITypeOrString[]

Arguments to an FFI function (C ABI)

Defaults to an empty array, which means no arguments.

To pass a pointer, use "ptr" or "pointer" as the type name. To get a pointer, see ptr.

From JavaScript:

import { dlopen, FFIType, suffix } from "bun:ffi"

const lib = dlopen(`adder.${suffix}`, {
	add: {
		// FFIType can be used or you can pass string labels.
		args: [FFIType.i32, "i32"],
		returns: "i32",
	},
})
lib.symbols.add(1, 2)

In C:

int add(int a, int b) {
  return a + b;
}

readonly ptr?: bigint | Pointer
Function pointer to the native function
If provided, Bun uses this pointer instead of looking the function up with dlsym(). It should not be null (0).
Use this when the library is already loaded, or when the module is also using Node-API.

readonly returns?: FFITypeOrString

Return type of an FFI function (C ABI)

Defaults to FFIType.void

To pass a pointer, use "ptr" or "pointer" as the type name. To get a pointer, see ptr.

From JavaScript:

import { dlopen, CString } from "bun:ffi"

const lib = dlopen('z', {
   version: {
     returns: "ptr",
  }
});
console.log(new CString(lib.symbols.version()));

In C:

char* version()
{
 return "1.0.0";
}

readonly threadsafe?: boolean
Whether C/FFI code can call this function from a separate thread.
Only supported with JSCallback.
This does not make the function run in a separate thread; the application or library is still responsible for its own threading.
Enabling it adds a small cost to every call, so it's only worth it when that cost is smaller than what you gain from running the function on a separate thread.