Types

Introspection

New in Koffi 2.0: koffi.resolve(), new in Koffi 2.2: koffi.offsetof()

Use koffi.introspect(type) to get detailed information about a type: name, primitive, size, alignment, members (record types), reference type (array, pointer) and length (array).

const FoobarType = koffi.struct('FoobarType', {
    a: 'int',
    b: 'char *',
    c: 'double'
});

console.log(koffi.introspect(FoobarType));

// Expected result on 64-bit machines:
// {
//     name: 'FoobarType',
//     primitive: 'Record',
//     size: 24,
//     alignment: 8,
//     members: {
//         a: { name: 'a', type: [External: 4b28a60], offset: 0 },
//         b: { name: 'b', type: [External: 4b292e0], offset: 8 },
//         c: { name: 'c', type: [External: 4b29260], offset: 16 }
//     }
// }

Koffi also exposes a few more utility functions to get a subset of this information:

• koffi.sizeof(type) to get the size of a type
• koffi.alignof(type) to get the alignment of a type
• koffi.offsetof(type, member_name) to get the offset of a record member
• koffi.resolve(type) to get the resolved type object from a type string

Just like before, you can refer to primitive types by their name or through koffi.types:

// These two lines do the same:
console.log(koffi.sizeof('long'));
console.log(koffi.sizeof(koffi.types.long));

Aliases

New in Koffi 2.0

You can alias a type with koffi.alias(name, type). Aliased types are completely equivalent.

Settings

Memory usage

For synchronous/normal calls, Koffi uses two preallocated memory blocks:

• One to construct the C stack and assign registers, subsequently used by the platform-specific assembly code (1 MiB by default)
• One to allocate strings and objects/structs (2 MiB by default)

Unless very big strings or objects (at least more than one page of memory) are used, Koffi does not directly allocate any extra memory during calls or callbacks. However, please note that the JS engine (V8) might.

The size (in bytes) of these preallocated blocks can be changed. Use koffi.config() to get an object with the settings, and koffi.config(obj) to apply new settings.

let config = koffi.config();
console.log(config);

The same is true for asynchronous calls. When an asynchronous call is made, Koffi will allocate new blocks unless there is an unused (resident) set of blocks still available. Once the asynchronous call is finished, these blocks are freed if there are more than resident_async_pools sets of blocks left around.

There cannot be more than max_async_calls running at the same time.

Default settings

Usage statistics

New in Koffi 2.3.2

You can use koffi.stats() to get a few statistics related to Koffi.

POSIX error codes

New in Koffi 2.3.14

You can use koffi.errno() to get the current errno value, and koffi.errno(value) to change it.

The standard POSIX error codes are available in koffi.os.errno, as shown below:

const assert = require('assert');

// ES6 syntax: import koffi from 'koffi';
const koffi = require('koffi');

const lib = koffi.load('libc.so.6');

const close = lib.func('int close(int fd)');

close(-1);
assert.equal(koffi.errno(), koffi.os.errno.EBADF);

console.log('close() with invalid FD is POSIX compliant!');

Reset internal state

New in Koffi 2.5.19

You can use koffi.reset() to clear some Koffi internal state such as:

• Parser type names
• Asynchronous function broker (useful to avoid false positive with jest --detectOpenHandles)

This function is mainly intended for test code, when you execute the same code over and over and you need to reuse type names.