Input parameters#

Primitive types#

Standard types#

While the C standard allows for variation in the size of most integer types, Koffi enforces the same definition for most primitive types, listed below:

C type

JS type

Bytes

Signedness

Note

void

Undefined

0

Only valid as a return type

int8, int8_t

Number (integer)

1

Signed

uint8, uint8_t

Number (integer)

1

Unsigned

char

Number (integer)

1

Signed

uchar, unsigned char

Number (integer)

1

Unsigned

char16, char16_t

Number (integer)

2

Signed

int16, int16_t

Number (integer)

2

Signed

uint16, uint16_t

Number (integer)

2

Unsigned

short

Number (integer)

2

Signed

ushort, unsigned short

Number (integer)

2

Unsigned

int32, int32_t

Number (integer)

4

Signed

uint32, uint32_t

Number (integer)

4

Unsigned

int

Number (integer)

4

Signed

uint, unsigned int

Number (integer)

4

Unsigned

int64, int64_t

Number (integer)

8

Signed

uint64, uint64_t

Number (integer)

8

Unsigned

longlong, long long

Number (integer)

8

Signed

ulonglong, unsigned long long

Number (integer)

8

Unsigned

float32

Number (float)

4

float64

Number (float)

8

float

Number (float)

4

double

Number (float)

8

Koffi also accepts BigInt values when converting from JS to C integers. If the value exceeds the range of the C type, Koffi will convert the number to an undefined value. In the reverse direction, BigInt values are automatically used when needed for big 64-bit integers.

Koffi defines a few more types that can change size depending on the OS and the architecture:

C type

JS type

Signedness

Note

bool

Boolean

Usually one byte

long

Number (integer)

Signed

4 or 8 bytes depending on platform (LP64, LLP64)

ulong

Number (integer)

Unsigned

4 or 8 bytes depending on platform (LP64, LLP64)

unsigned long

Number (integer)

Unsigned

4 or 8 bytes depending on platform (LP64, LLP64)

intptr

Number (integer)

Signed

4 or 8 bytes depending on register width

intptr_t

Number (integer)

Signed

4 or 8 bytes depending on register width

uintptr

Number (integer)

Unsigned

4 or 8 bytes depending on register width

uintptr_t

Number (integer)

Unsigned

4 or 8 bytes depending on register width

str, string

String

JS strings are converted to and from UTF-8

str16, string16

String

JS strings are converted to and from UTF-16 (LE)

Primitive types can be specified by name (in a string) or through koffi.types:

1// These two lines do the same:
2let struct1 = koffi.struct({ dummy: 'long' });
3let struct2 = koffi.struct({ dummy: koffi.types.long });

Endian-sensitive integers#

New in Koffi 2.1

Koffi defines a bunch of endian-sensitive types, which can be used when dealing with binary data (network payloads, binary file formats, etc.).

C type

Bytes

Signedness

Endianness

int16_le, int16_le_t

2

Signed

Little Endian

int16_be, int16_be_t

2

Signed

Big Endian

uint16_le, uint16_le_t

2

Unsigned

Little Endian

uint16_be, uint16_be_t

2

Unsigned

Big Endian

int32_le, int32_le_t

4

Signed

Little Endian

int32_be, int32_be_t

4

Signed

Big Endian

uint32_le, uint32_le_t

4

Unsigned

Little Endian

uint32_be, uint32_be_t

4

Unsigned

Big Endian

int64_le, int64_le_t

8

Signed

Little Endian

int64_be, int64_be_t

8

Signed

Big Endian

uint64_le, uint64_le_t

8

Unsigned

Little Endian

uint64_be, uint64_be_t

8

Unsigned

Big Endian

Struct types#

Struct definition#

Koffi converts JS objects to C structs, and vice-versa.

Unlike function declarations, as of now there is only one way to create a struct type, with the koffi.struct() function. This function takes two arguments: the first one is the name of the type, and the second one is an object containing the struct member names and types. You can omit the first argument to declare an anonymous struct.

The following example illustrates how to declare the same struct in C and in JS with Koffi:

1typedef struct A {
2    int a;
3    char b;
4    const char *c;
5    struct {
6        double d1;
7        double d2;
8    } d;
9} A;

1const A = koffi.struct('A', {
2    a: 'int',
3    b: 'char',
4    c: 'const char *', // Koffi does not care about const, it is ignored
5    d: koffi.struct({
6        d1: 'double',
7        d2: 'double'
8    })
9});

Koffi automatically follows the platform C ABI regarding alignment and padding. However, you can override these rules if needed with:

  • Pack all members without padding with koffi.pack() (instead of koffi.struct())

  • Change alignment of a specific member as shown below

 1// This struct is 3 bytes long
 2const PackedStruct = koffi.pack('PackedStruct', {
 3    a: 'int8_t',
 4    b: 'int16_t'
 5});
 6
 7// This one is 10 bytes long, the second member has an alignment requirement of 8 bytes
 8const BigStruct = koffi.struct('BigStruct', {
 9    a: 'int8_t',
10    b: [8, 'int16_t']
11})

Once a struct is declared, you can use it by name (with a string, like you can do for primitive types) or through the value returned by the call to koffi.struct(). Only the latter is possible when declaring an anonymous struct.

1// The following two function declarations are equivalent, and declare a function taking an A value and returning A
2const Function1 = lib.func('A Function(A value)');
3const Function2 = lib.func('Function', A, [A]);

Opaque types#

Many C libraries use some kind of object-oriented API, with a pair of functions dedicated to create and delete objects. An obvious example of this can be found in stdio.h, with the opaque FILE * pointer. You can open and close files with fopen() and fclose(), and manipule the opaque pointer with other functions such as fread() or ftell().

In Koffi, you can manage this with opaque types. Declare the opaque type with koffi.opaque(name), and use a pointer to this type either as a return type or some kind of output parameter (with a double pointer).

Note

Opaque types have changed in version 2.0, and again in version 2.1.

In Koffi 1.x, opaque handles 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, and use an array for output parameters. This is shown in the example below (look for the call to ConcatNewOut in the JS part), and is described in the section on output parameters.

In addition to this, you should use koffi.opaque() (introduced in Koffi 2.1) instead of koffi.handle() which is deprecated, and will be removed eventually in Koffi 3.0.

Consult the migration guide for more information.

The full example below implements an iterative string builder (concatenator) in C, and uses it from Javascript to output a mix of Hello World and FizzBuzz. The builder is hidden behind an opaque type, and is created and destroyed using a pair of C functions: ConcatNew (or ConcatNewOut) and ConcatFree.

  1// Build with: clang -fPIC -o handles.so -shared handles.c -Wall -O2
  2
  3#include <stdlib.h>
  4#include <stdbool.h>
  5#include <stdio.h>
  6#include <errno.h>
  7#include <string.h>
  8
  9typedef struct Fragment {
 10    struct Fragment *next;
 11
 12    size_t len;
 13    char str[];
 14} Fragment;
 15
 16typedef struct Concat {
 17    Fragment *first;
 18    Fragment *last;
 19
 20    size_t total;
 21} Concat;
 22
 23bool ConcatNewOut(Concat **out)
 24{
 25    Concat *c = malloc(sizeof(*c));
 26    if (!c) {
 27        fprintf(stderr, "Failed to allocate memory: %s\n", strerror(errno));
 28        return false;
 29    }
 30
 31    c->first = NULL;
 32    c->last = NULL;
 33    c->total = 0;
 34
 35    *out = c;
 36    return true;
 37}
 38
 39Concat *ConcatNew()
 40{
 41    Concat *c = NULL;
 42    ConcatNewOut(&c);
 43    return c;
 44}
 45
 46void ConcatFree(Concat *c)
 47{
 48    if (!c)
 49        return;
 50
 51    Fragment *f = c->first;
 52
 53    while (f) {
 54        Fragment *next = f->next;
 55        free(f);
 56        f = next;
 57    }
 58
 59    free(c);
 60}
 61
 62bool ConcatAppend(Concat *c, const char *frag)
 63{
 64    size_t len = strlen(frag);
 65
 66    Fragment *f = malloc(sizeof(*f) + len + 1);
 67    if (!f) {
 68        fprintf(stderr, "Failed to allocate memory: %s\n", strerror(errno));
 69        return false;
 70    }
 71
 72    f->next = NULL;
 73    if (c->last) {
 74        c->last->next = f;
 75    } else {
 76        c->first = f;
 77    }
 78    c->last = f;
 79    c->total += len;
 80
 81    f->len = len;
 82    memcpy(f->str, frag, len);
 83    f->str[len] = 0;
 84
 85    return true;
 86}
 87
 88const char *ConcatBuild(Concat *c)
 89{
 90    Fragment *r = malloc(sizeof(*r) + c->total + 1);
 91    if (!r) {
 92        fprintf(stderr, "Failed to allocate memory: %s\n", strerror(errno));
 93        return NULL;
 94    }
 95
 96    r->next = NULL;
 97    r->len = 0;
 98
 99    Fragment *f = c->first;
100
101    while (f) {
102        Fragment *next = f->next;
103
104        memcpy(r->str + r->len, f->str, f->len);
105        r->len += f->len;
106
107        free(f);
108        f = next;
109    }
110    r->str[r->len] = 0;
111
112    c->first = r;
113    c->last = r;
114
115    return r->str;
116}

 1// ES6 syntax: import koffi from 'koffi';
 2const koffi = require('koffi');
 3
 4const lib = koffi.load('./handles.so');
 5
 6const Concat = koffi.opaque('Concat');
 7const ConcatNewOut = lib.func('bool ConcatNewOut(_Out_ Concat **out)');
 8const ConcatNew = lib.func('Concat *ConcatNew()');
 9const ConcatFree = lib.func('void ConcatFree(Concat *c)');
10const ConcatAppend = lib.func('bool ConcatAppend(Concat *c, const char *frag)');
11const ConcatBuild = lib.func('const char *ConcatBuild(Concat *c)');
12
13let c = ConcatNew();
14if (!c) {
15    // This is stupid, it does the same, but try both versions (return value, output parameter)
16    let ptr = [null];
17    if (!ConcatNewOut(ptr))
18        throw new Error('Allocation failure');
19    c = ptr[0];
20}
21
22try {
23    if (!ConcatAppend(c, 'Hello... '))
24        throw new Error('Allocation failure');
25    if (!ConcatAppend(c, 'World!\n'))
26        throw new Error('Allocation failure');
27
28    for (let i = 1; i <= 30; i++) {
29        let frag;
30        if (i % 15 == 0) {
31            frag = 'FizzBuzz';
32        } else if (i % 5 == 0) {
33            frag = 'Buzz';
34        } else if (i % 3 == 0) {
35            frag = 'Fizz';
36        } else {
37            frag = String(i);
38        }
39
40        if (!ConcatAppend(c, frag))
41            throw new Error('Allocation failure');
42        if (!ConcatAppend(c, ' '))
43            throw new Error('Allocation failure');
44    }
45
46    let str = ConcatBuild(c);
47    if (str == null)
48        throw new Error('Allocation failure');
49    console.log(str);
50} finally {
51    ConcatFree(c);
52}

Array types#

Fixed-size C arrays#

Changed in Koffi 2.7.1

Fixed-size arrays are declared with koffi.array(type, length). Just like in C, they cannot be passed as functions parameters (they degenerate to pointers), or returned by value. You can however embed them in struct types.

Koffi applies the following conversion rules when passing arrays to/from C:

  • JS to C: Koffi can take a normal Array (e.g. [1, 2]) or a TypedArray of the correct type (e.g. Uint8Array for an array of uint8_t numbers)

  • C to JS (return value, output parameters, callbacks): Koffi will use a TypedArray if possible. But you can change this behavior when you create the array type with the optional hint argument: koffi.array('uint8_t', 64, 'Array'). For non-number types, such as arrays of strings or structs, Koffi creates normal arrays.

See the example below:

 1// ES6 syntax: import koffi from 'koffi';
 2const koffi = require('koffi');
 3
 4// Those two structs are exactly the same, only the array conversion hint is different
 5const Foo1 = koffi.struct('Foo1', {
 6    i: 'int',
 7    a16: koffi.array('int16_t', 2)
 8});
 9const Foo2 = koffi.struct('Foo2', {
10    i: 'int',
11    a16: koffi.array('int16_t', 2, 'Array')
12});
13
14// Uses an hypothetical C function that just returns the struct passed as a parameter
15const ReturnFoo1 = lib.func('Foo1 ReturnFoo(Foo1 p)');
16const ReturnFoo2 = lib.func('Foo2 ReturnFoo(Foo2 p)');
17
18console.log(ReturnFoo1({ i: 5, a16: [6, 8] })) // Prints { i: 5, a16: Int16Array(2) [6, 8] }
19console.log(ReturnFoo2({ i: 5, a16: [6, 8] })) // Prints { i: 5, a16: [6, 8] }

You can also declare arrays with the C-like short syntax in type declarations, as shown below:

1const StructType = koffi.struct('StructType', {
2    f8: 'float [8]',
3    self4: 'StructType *[4]'
4});

Note

The short C-like syntax was introduced in Koffi 2.7.1, use koffi.array() for older versions.

Fixed-size string buffers#

Koffi can also convert JS strings to fixed-sized arrays in the following cases:

  • char arrays are filled with the UTF-8 encoded string, truncated if needed. The buffer is always NUL-terminated.

  • char16 (or char16_t) arrays are filled with the UTF-16 encoded string, truncated if needed. The buffer is always NUL-terminated.

The reverse case is also true, Koffi can convert a C fixed-size buffer to a JS string. This happens by default for char, char16 and char16_t arrays, but you can also explicitly ask for this with the String array hint (e.g. koffi.array('char', 8, 'String')).

Dynamic arrays (pointers)#

In C, dynamically-sized arrays are usually passed around as pointers. Read more about array pointers in the relevant section.

Union types#

The declaration and use of unions types will be explained in a later section, they are only briefly mentioned here if you need them.