Functions#

Function definitions#

To declare functions, start by loading the shared library with koffi.load(filename).

1const koffi = require('koffi');
2const lib = koffi.load('/path/to/shared/library'); // File extension depends on platforms: .so, .dll, .dylib, etc.

You can use the returned object to load C functions from the library. To do so, you can use two syntaxes:

  • The classic syntax, inspired by node-ffi

  • C-like prototypes

Classic syntax#

To declare a function, you need to specify its non-mangled name, its return type, and its parameters. Use an ellipsis as the last parameter for variadic functions.

1const printf = lib.func('printf', 'int', ['str', '...']);
2const atoi = lib.func('atoi', 'int', ['str']);

Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section on calling conventions for more information on this subject.

C-like prototypes#

If you prefer, you can declare functions using simple C-like prototype strings, as shown below:

1const printf = lib.func('int printf(const char *fmt, ...)');
2const atoi = lib.func('int atoi(str)'); // The parameter name is not used by Koffi, and optional

You can use () or (void) for functions that take no argument.

Function calls#

Calling conventions#

By default, calling a C function happens synchronously.

Most architectures only support one procedure call standard per process. The 32-bit x86 platform is an exception to this, and Koffi supports several x86 conventions:

Convention

Classic form

Prototype form

Description

Cdecl

koffi.cdecl or koffi.func

(default)

This is the default convention, and the only one on other platforms

Stdcall

koffi.stdcall

__stdcall

This convention is used extensively within the Win32 API

Fastcall

koffi.fastcall

__fastcall

Rarely used, uses ECX and EDX for first two parameters

Thiscall

koffi.thiscall

__thiscall

Rarely used, uses ECX for first parameter

You can safely use these on non-x86 platforms, they are simply ignored.

Below you can find a small example showing how to use a non-default calling convention, with the two syntaxes:

1const koffi = require('koffi');
2const lib = koffi.load('user32.dll');
3
4// The following two declarations are equivalent, and use stdcall on x86 (and the default ABI on other platforms)
5const MessageBoxA_1 = lib.stdcall('MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
6const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');

Asynchronous calls#

You can issue asynchronous calls by calling the function through its async member. In this case, you need to provide a callback function as the last argument, with (err, res) parameters.

 1const koffi = require('koffi');
 2const lib = koffi.load('libc.so.6');
 3
 4const atoi = lib.func('int atoi(const char *str)');
 5
 6atoi.async('1257', (err, res) => {
 7    console.log('Result:', res);
 8})
 9console.log('Hello World!');
10
11// This program will print:
12//   Hello World!
13//   Result: 1257

These calls are executed by worker threads. It is your responsibility to deal with data sharing issues in the native code that may be caused by multi-threading.

You can easily convert this callback-style async function to a promise-based version with util.promisify() from the Node.js standard library.

Variadic functions cannot be called asynchronously.

Variadic functions#

Variadic functions are declared with an ellipsis as the last argument.

In order to call a variadic function, you must provide two Javascript arguments for each additional C parameter, the first one is the expected type and the second one is the value.

1const printf = lib.func('printf', 'int', ['str', '...']);
2
3// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
4printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');

On x86 platforms, only the Cdecl convention can be used for variadic functions.

Special considerations#

Output parameters#

By default, Koffi will only forward arguments from Javascript to C. However, many C functions use pointer arguments for output values, or input/output values.

For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) two types of parameters:

In order to change an argument from input-only to output or input/output, use the following functions:

  • koffi.out() on a pointer, e.g. koffi.out(koffi.pointer(timeval)) (where timeval is a struct type)

  • koffi.inout() for dual input/output parameters

The same can be done when declaring a function with a C-like prototype string, with the MSDN-like type qualifiers:

  • _Out_ for output parameters

  • _Inout_ for dual input/output parameters

Struct example#

This example calls the POSIX function gettimeofday(), and uses the prototype-like syntax.

 1const koffi = require('koffi');
 2const lib = koffi.load('libc.so.6');
 3
 4const timeval = koffi.struct('timeval', {
 5    tv_sec: 'unsigned int',
 6    tv_usec: 'unsigned int'
 7});
 8const timezone = koffi.struct('timezone', {
 9    tz_minuteswest: 'int',
10    tz_dsttime: 'int'
11});
12
13// The _Out_ qualifiers instruct Koffi to marshal out the values
14const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
15
16let tv = {};
17gettimeofday(tv, null);
18
19console.log(tv);

Opaque type example#

This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.

 1const koffi = require('koffi');
 2const lib = koffi.load('sqlite3.so');
 3
 4const sqlite3 = koffi.opaque('sqlite3');
 5
 6// Use koffi.out() on a double pointer to copy out (from C to JS) after the call
 7const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['str', koffi.out(koffi.pointer(sqlite3, 2)), 'int', 'str']);
 8const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [koffi.pointer(sqlite3)]);
 9
10const SQLITE_OPEN_READWRITE = 0x2;
11const SQLITE_OPEN_CREATE = 0x4;
12
13let out = [null];
14if (sqlite3_open_v2(':memory:', out, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
15    throw new Error('Failed to open database');
16let db = out[0];
17
18sqlite3_close_v2(db);

Polymorphic parameters#

New in Koffi 2.1

Many C functions use void * parameters in order to pass polymorphic objects and arrays, meaning that the data format changes can change depending on one other argument, or on some kind of struct tag member.

Koffi provides two features to deal with this:

  • Typed JS arrays can be used as values in place everywhere void * is expected. See dynamic arrays for more information, for input or output.

  • You can use koffi.as(value, type) to tell Koffi what kind of type is actually expected.

The example below shows the use of koffi.as() to read the header of a PNG file with fread().

 1const koffi = require('koffi');
 2const lib = koffi.load('libc.so.6');
 3
 4const FILE = koffi.opaque('FILE');
 5
 6const PngHeader = koffi.pack('PngHeader', {
 7    signature: koffi.array('uint8_t', 8),
 8    ihdr: koffi.pack({
 9        length: 'uint32_be_t',
10        chunk: koffi.array('char', 4),
11        width: 'uint32_be_t',
12        height: 'uint32_be_t',
13        depth: 'uint8_t',
14        color: 'uint8_t',
15        compression: 'uint8_t',
16        filter: 'uint8_t',
17        interlace: 'uint8_t',
18        crc: 'uint32_be_t'
19    })
20});
21
22const fopen = lib.func('FILE *fopen(const char *path, const char *mode)');
23const fclose = lib.func('int fclose(FILE *fp)');
24const fread = lib.func('size_t fread(_Out_ void *ptr, size_t size, size_t nmemb, FILE *fp)');
25
26let filename = process.argv[2];
27if (filename == null)
28    throw new Error('Usage: node png.js <image.png>');
29
30let hdr = {};
31{
32
33    let fp = fopen(filename, 'rb');
34    if (!fp)
35        throw new Error(`Failed to open '${filename}'`);
36
37    try {
38        let len = fread(koffi.as(hdr, 'PngHeader *'), 1, koffi.sizeof(PngHeader), fp);
39        if (len < koffi.sizeof(PngHeader))
40            throw new Error('Failed to read PNG header');
41    } finally {
42        fclose(fp);
43    }
44}
45
46console.log('PNG header:', hdr);

Heap-allocated values#

New in Koffi 2.0

Some C functions return heap-allocated values directly or through output parameters. While Koffi automatically converts values from C to JS (to a string or an object), it does not know when something needs to be freed, or how.

For opaque types, such as FILE, this does not matter because you will explicitly call fclose() on them. But some values (such as strings) get implicitly converted by Koffi, and you lose access to the original pointer. This creates a leak if the string is heap-allocated.

To avoid this, you can instruct Koffi to call a function on the original pointer once the conversion is done, by creating a disposable type with koffi.dispose(name, type, func). This creates a type derived from another type, the only difference being that func gets called with the original pointer once the value has been converted and is not needed anymore.

The name can be omitted to create an anonymous disposable type. If func is omitted or is null, Koffi will use koffi.free(ptr) (which calls the standard C library free function under the hood).

1const AnonHeapStr = koffi.disposable('str'); // Anonymous type (cannot be used in function prototypes)
2const NamedHeapStr = koffi.disposable('HeapStr', 'str'); // Same thing, but named so usable in function prototypes
3const ExplicitFree = koffi.disposable('HeapStr16', 'str16', koffi.free); // You can specify any other JS function

The following example illustrates the use of a disposable type derived from str.

1const koffi = require('koffi');
2const lib = koffi.load('libc.so.6');
3
4// You can also use: const strdup = lib.func('const char *! strdup(const char *str)')
5const HeapStr = koffi.disposable('str');
6const strdup = lib.cdecl('strdup', HeapStr, ['str']);
7
8let copy = strdup('Hello!');
9console.log(copy); // Prints Hello!

When you declare functions with the prototype-like syntax, you can either use named disposable types or use the ‘!’ shortcut qualifier with compatibles types, as shown in the example below. This qualifier creates an anonymous disposable type that calls koffi.free(ptr).

1const koffi = require('koffi');
2const lib = koffi.load('libc.so.6');
3
4// You can also use: const strdup = lib.func('const char *! strdup(const char *str)')
5const strdup = lib.func('str! strdup(const char *str)');
6
7let copy = strdup('World!');
8console.log(copy); // Prints World!

Disposable types can only be created from pointer or string types.

Warning

Be careful on Windows: if your shared library uses a different CRT (such as msvcrt), the memory could have been allocated by a different malloc/free implementation or heap, resulting in undefined behavior if you use koffi.free().

Javascript callbacks#

In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.

1const koffi = require('koffi');
2
3// With the classic syntax, this callback expects an integer and returns nothing
4const ExampleCallback = koffi.callback('ExampleCallback', 'void', ['int']);
5
6// With the prototype parser, this callback expects a double and float, and returns the sum as a double
7const AddDoubleFloat = koffi.callback('double AddDoubleFloat(double d, float f)');

Once your callback type is declared, you can use a pointer to it in struct definitions, or as function parameters and/or return types.

Note

Callbacks have changed in version 2.0.

In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.

Now, you must use them through a pointer: void CallIt(CallbackType func) in Koffi 1.x becomes void CallIt(CallbackType *func) in version 2.0 and newer.

Consult the migration guide for more information.

Koffi only uses predefined static trampolines, and does not need to generate code at runtime, which makes it compatible with platforms with hardened W^X migitations (such as PaX mprotect). However, this imposes some restrictions on the maximum number of callbacks, and their duration.

Thus, Koffi distinguishes two callback modes:

  • Transient callbacks can only be called while the C function they are passed to is running, and are invalidated when it returns. If the C function calls the callback later, the behavior is undefined, though Koffi tries to detect such cases. If it does, an exception will be thrown, but this is no guaranteed. However, they are simple to use, and don’t require any special handling.

  • Registered callbacks can be called at any time, but they must be manually registered and unregistered. A limited number of registered callbacks can exist at the same time.

You need to specify the correct calling convention on x86 platforms, or the behavior is undefined (Node will probably crash). Only cdecl and stdcall callbacks are supported.

Transient callbacks#

Use transient callbacks when the native C function only needs to call them while it runs (e.g. qsort, progress callback, sqlite3_exec). Here is a small example with the C part and the JS part.

1#include <string.h>
2
3int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
4{
5    char buf[64];
6    snprintf(buf, sizeof(buf), "Hello %s!", str);
7    return cb(buf, age);
8}
 1const koffi = require('koffi');
 2const lib = koffi.load('./callbacks.so'); // Fake path
 3
 4const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
 5
 6const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
 7
 8let ret = TransferToJS('Niels', 27, (str, age) => {
 9    console.log(str);
10    console.log('Your age is:', age);
11    return 42;
12});
13console.log(ret);
14
15// This example prints:
16//   Hello Niels!
17//   Your age is: 27
18//   42

Registered callbacks#

New in Koffi 2.0

Use registered callbacks when the function needs to be called at a later time (e.g. log handler, event handler, fopencookie/funopen). Call koffi.register(func, type) to register a callback function, with two arguments: the JS function, and the callback type.

When you are done, call koffi.unregister() (with the value returned by koffi.register()) to release the slot. A maximum of 16 registered callbacks can exist at the same time. Failure to do so will leak the slot, and subsequent registrations may fail (with an exception) once all slots are used.

The example below shows how to register and unregister delayed callbacks.

 1static const char *(*g_cb1)(const char *name);
 2static void (*g_cb2)(const char *str);
 3
 4void RegisterFunctions(const char *(*cb1)(const char *name), void (*cb2)(const char *str))
 5{
 6    g_cb1 = cb1;
 7    g_cb2 = cb2;
 8}
 9
10void SayIt(const char *name)
11{
12    const char *str = g_cb1(name);
13    g_cb2(str);
14}
 1const koffi = require('koffi');
 2const lib = koffi.load('./callbacks.so'); // Fake path
 3
 4const GetCallback = koffi.callback('const char *GetCallback(const char *name)');
 5const PrintCallback = koffi.callback('void PrintCallback(const char *str)');
 6
 7const RegisterFunctions = lib.func('void RegisterFunctions(GetCallback *cb1, PrintCallback *cb2)');
 8const SayIt = lib.func('void SayIt(const char *name)');
 9
10let cb1 = koffi.register(name => 'Hello ' + name + '!', koffi.pointer(GetCallback));
11let cb2 = koffi.register(console.log, 'PrintCallback *');
12
13RegisterFunctions(cb1, cb2);
14SayIt('Kyoto'); // Prints Hello Kyoto!
15
16koffi.unregister(cb1);
17koffi.unregister(cb2);

Handling of exceptions#

If an exception happens inside the JS callback, the C API will receive 0 or NULL (depending on the return value type).

Handle the exception yourself (with try/catch) if you need to handle exceptions differently.

Thread safety#

Asynchronous functions run on worker threads. You need to deal with thread safety issues if you share data between threads.

Callbacks must be called from the main thread, or more precisely from the same thread as the V8 intepreter. Calling a callback from another thread is undefined behavior, and will likely lead to a crash or a big mess. You’ve been warned!