Koffi

https://koffi.dev/
Admin
Koffi is a fast and easy-to-use C FFI module for Node.js that enables calling C functions and using...
Tokens:53,130
Snippets:442
Trust Score:6.6
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install Koffi with npm

Source: https://koffi.dev/start

Use this command to install the Koffi package via npm.

```sh
npm install koffi
```

--------------------------------

### Windows Example: Show Message Box

Source: https://koffi.dev/start

This example uses MessageBoxA and MessageBoxW from the Win32 API to display a message box. It demonstrates the x86 stdcall calling convention and UTF-8/UTF-16 string arguments.

```js
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

// Load the shared library
const lib = koffi.load('user32.dll');

// Declare constants
const MB_OK = 0x0;
const MB_YESNO = 0x4;
const MB_ICONQUESTION = 0x20;
const MB_ICONINFORMATION = 0x40;
const IDOK = 1;
const IDYES = 6;
const IDNO = 7;

// Find functions
const MessageBoxA = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
const MessageBoxW = lib.func('__stdcall', 'MessageBoxW', 'int', ['void *', 'str16', 'str16', 'uint']);

let ret = MessageBoxA(null, 'Do you want another message box?', 'Koffi', MB_YESNO | MB_ICONQUESTION);

if (ret == IDYES)
    MessageBoxW(null, 'Hello World!', 'Koffi', MB_ICONINFORMATION);
```

--------------------------------

### Write to file using koffi.view() and mmap

Source: https://koffi.dev/pointers

Linux example that writes 'Hello World!' to 'hello.txt' using mmap and koffi.view(). It defines required constants (O_*, PROT_*, MAP_*) and loads libc functions. Note: constants are Linux-specific and may differ on other systems. The example uses koffi.errno() for error handling.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

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

const mode_t = koffi.alias('mode_t', 'uint32_t');
const off_t = koffi.alias('off_t', 'int64_t');

// These values are used on Linux and may differ on other systems
const O_RDONLY = 00000000;
const O_WRONLY = 00000001;
const O_RDWR = 00000002;
const O_CREAT = 00000100;
const O_EXCL = 00000200;
const O_CLOEXEC = 02000000;

// These values are used on Linux and may differ on other systems
const PROT_READ = 0x01;
const PROT_WRITE = 0x02;
const PROT_EXEC = 0x04;
const MAP_SHARED = 0x01;
const MAP_PRIVATE = 0x02;

const open = libc.func('int open(const char *path, int flags, uint32_t mode)');
const close = libc.func('int close(int fd)');
const ftruncate = libc.func('int ftruncate(int fd, off_t length)');
const mmap = libc.func('void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset)');
const munmap = libc.func('int munmap(void *addr, size_t length)');
const strerror = libc.func('const char *strerror(int errnum)');

write('hello.txt', 'Hello World!');

function write(filename, str) {
    let fd = -1;
    let ptr = null;

    // Work with encoded string
    str = Buffer.from(str);

    try {
        fd = open(filename, O_CREAT | O_EXCL | O_RDWR | O_CLOEXEC, 0644);
        if (fd < 0)
            throw new Error(`Failed to create '${filename}': ` + strerror(koffi.errno()));

        if (ftruncate(fd, str.length) < 0)
            throw new Error(`Failed to resize '${filename}': ` + strerror(koffi.errno()));

        ptr = mmap(null, str.length, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
        if (ptr == null)
            throw new Error(`Failed to map '${filename}' to memory: ` + strerror(koffi.errno()));

        let ab = koffi.view(ptr, str.length);
        let view = new Uint8Array(ab);

        str.copy(view);
     } finally {
        if (ptr != null)
            munmap(ptr, str.length);
        close(fd);
    }
}
```

--------------------------------

### Linux Example: Print Current Time

Source: https://koffi.dev/start

This example uses gettimeofday(), localtime_r(), and printf() to print the current time. It demonstrates output parameters and variadic functions.

```js
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

// Load the shared library
const lib = koffi.load('libc.so.6');

// Declare struct types
const timeval = koffi.struct('timeval', {
    tv_sec: 'unsigned int',
    tv_usec: 'unsigned int'
});
const timezone = koffi.struct('timezone', {
    tz_minuteswest: 'int',
    tz_dsttime: 'int'
});
const time_t = koffi.struct('time_t', { value: 'int64_t' });
const tm = koffi.struct('tm', {
    tm_sec: 'int',
    tm_min: 'int',
    tm_hour: 'int',
    tmay: 'int',
    tm_mon: 'int',
    tm_year: 'int',
    tm_wday: 'int',
    tm_yday: 'int',
    tm_isdst: 'int'
});

// Find functions
const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
const localtime_r = lib.func('tm *localtime_r(const time_t *timeval, _Out_ tm *result)');
const printf = lib.func('int printf(const char *format, ...)');

// Get local time
let tv = {};
let now = {};
gettimeofday(tv, null);
localtime_r({ value: tv.tv_sec }, now);

// And format it with printf (variadic function)
printf('Hello World!\n');
printf('Local time: %02d:%02d:%02d\n', 'int', now.tm_hour, 'int', now.tm_min, 'int', now.tm_sec);
```

--------------------------------

### Start and stop all machines

Source: https://koffi.dev/contribute

Start all available machines or stop everything. Machines stay active until stopped.

```sh
node tools/brew.js start # Start all available machines
node tools/brew.js stop # Stop everything
```

--------------------------------

### Win32 Example: Enumerate Chrome Windows with Output Parameters

Source: https://koffi.dev/output

This example demonstrates using Koffi to call Win32 functions with output parameters. It uses _Out_ qualifiers in function prototypes to retrieve a process ID and window title. The code loads user32.dll, defines necessary types, and iterates over Chrome windows, decoding the title from a buffer.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

const user32 = koffi.load('user32.dll');

const DWORD = koffi.alias('DWORD', 'uint32_t');
const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
const HWND = koffi.alias('HWND', HANDLE);

const FindWindowEx = user32.func('HWND __stdcall FindWindowExW(HWND hWndParent, HWND hWndChildAfter, const char16_t *lpszClass, const char16_t *lpszWindow)');
const GetWindowThreadProcessId = user32.func('DWORD __stdcall GetWindowThreadProcessId(HWND hWnd, _Out_ DWORD *lpdwProcessId)');
const GetWindowText = user32.func('int __stdcall GetWindowTextA(HWND hWnd, _Out_ uint8_t *lpString, int nMaxCount)');

for (let hwnd = null;;) {
    hwnd = FindWindowEx(0, hwnd, 'Chrome_WidgetWin_1', null);

    if (!hwnd)
        break;

    // Get PID
    let pid;
    {
        let ptr = [null];
        let tid = GetWindowThreadProcessId(hwnd, ptr);

        if (!tid) {
            // Maybe the process ended in-between?
            continue;
        }

        pid = ptr[0];
    }

    // Get window title
    let title;
    {
        let buf = Buffer.allocUnsafe(1024);
        let length = GetWindowText(hwnd, buf, buf.length);

        if (!length) {
            // Maybe the process ended in-between?
            continue;
        }

        title = koffi.decode(buf, 'char', length);
    }

    console.log({ PID: pid, Title: title });
}
```

--------------------------------

### Win32 SendInput example with unions

Source: https://koffi.dev/composites

Complete example that uses the SendInput Win32 API to emit the Win+D shortcut and hide windows. It defines MOUSEINPUT, KEYBDINPUT, HARDWAREINPUT, and INPUT structs, with INPUT containing an anonymous union. It then creates keyboard events and calls SendInput.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

// Win32 type and functions

const user32 = koffi.load('user32.dll');

const INPUT_MOUSE = 0;
const INPUT_KEYBOARD = 1;
const INPUT_HARDWARE = 2;

const KEYEVENTF_KEYUP = 0x2;
const KEYEVENTF_SCANCODE = 0x8;

const VK_LWIN = 0x5B;
const VK_D = 0x44;

const MOUSEINPUT = koffi.struct('MOUSEINPUT', {
    dx: 'long',
    dy: 'long',
    mouseData: 'uint32_t',
    dwFlags: 'uint32_t',
    time: 'uint32_t',
    dwExtraInfo: 'uintptr_t'
});
const KEYBDINPUT = koffi.struct('KEYBDINPUT', {
    wVk: 'uint16_t',
    wScan: 'uint16_t',
    dwFlags: 'uint32_t',
    time: 'uint32_t',
    dwExtraInfo: 'uintptr_t'
});
const HARDWAREINPUT = koffi.struct('HARDWAREINPUT', {
    uMsg: 'uint32_t',
    wParamL: 'uint16_t',
    wParamH: 'uint16_t'
});

const INPUT = koffi.struct('INPUT', {
    type: 'uint32_t',
    u: koffi.union({
        mi: MOUSEINPUT,
        ki: KEYBDINPUT,
        hi: HARDWAREINPUT
    })
});

const SendInput = user32.func('unsigned int __stdcall SendInput(unsigned int cInputs, INPUT *pInputs, int cbSize)');

// Show/hide desktop with Win+D shortcut

let events = [
    make_keyboard_event(VK_LWIN, true),
    make_keyboard_event(VK_D, true),
    make_keyboard_event(VK_D, false),
    make_keyboard_event(VK_LWIN, false)
];

SendInput(events.length, events, koffi.sizeof(INPUT));

// Utility

function make_keyboard_event(vk, down) {
    let event = {
        type: INPUT_KEYBOARD,
        u: {
            ki: {
                wVk: vk,
                wScan: 0,
                dwFlags: down ? 0 : KEYEVENTF_KEYUP,
                time: 0,
                dwExtraInfo: 0
            }
        }
    };

    return event;
}
```

--------------------------------

### Get VNC or SPICE port

Source: https://koffi.dev/contribute

Use the info command to get the VNC or SPICE port for a machine.

```sh
node tools/brew.js info debian_x64
```

--------------------------------

### Build Koffi on Windows

Source: https://koffi.dev/contribute

Run from the src/koffi directory after installing Visual Studio C++ workload, CMake, and Node.js 16+. Use the --debug flag for debug builds.

```sh
cd src/koffi
node ../cnoke/cnoke.js
```

--------------------------------

### C code for callback example

Source: https://koffi.dev/migration

C function that takes a callback and calls it with a formatted string.

```c
#include <string.h>

int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
{
    char buf[64];
    snprintf(buf, sizeof(buf), "Hello %s!", str);
    return cb(buf, age);
}
```

--------------------------------

### Registered Callback Example (C)

Source: https://koffi.dev/callbacks

C code that stores two function pointers for later use. The functions are registered and then called by SayIt.

```c
static const char *(*g_cb1)(const char *name);
static void (*g_cb2)(const char *str);

void RegisterFunctions(const char *(*cb1)(const char *name), void (*cb2)(const char *str))
{
    g_cb1 = cb1;
    g_cb2 = cb2;
}

void SayIt(const char *name)
{
    const char *str = g_cb1(name);
    g_cb2(str);
}

```

--------------------------------

### Transient pointer example using memcpy and koffi.decode

Source: https://koffi.dev/output

This example demonstrates using a buffer as a transient output pointer. It copies a struct using memcpy into a Buffer, then decodes the buffer back to a JS object with koffi.decode. The buffer is only used during the function call, which is safe for transient pointers.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

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

const Vec3 = koffi.struct('Vec3', {
    x: 'float32',
    y: 'float32',
    z: 'float32'
})

const memcpy = lib.func('void *memcpy(_Out_ void *dest, const void *src, size_t size)');

let vec1 = { x: 1, y: 2, z: 3 };
let vec2 = null;

// Copy the vector in a convoluted way through memcpy
{
    let src = koffi.as(vec1, 'Vec3 *');
    let dest = Buffer.allocUnsafe(koffi.sizeof(Vec3));

    memcpy(dest, src, koffi.sizeof(Vec3));

    vec2 = koffi.decode(dest, Vec3);
}

// CHange vector1, leaving copy alone
[vec1.x, vec1.y, vec1.z] = [vec1.z, vec1.y, vec1.x];

console.log(vec1); // { x: 3, y: 2, z: 1 }
console.log(vec2); // { x: 1, y: 2, z: 3 }
```

--------------------------------

### Fixed-size array conversion example

Source: https://koffi.dev/composites

Shows how to declare fixed-size arrays with koffi.array and the optional 'Array' hint, and how Koffi converts between JS arrays and TypedArrays when passing to and from C functions.

```JavaScript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

// Those two structs are exactly the same, only the array conversion hint is different
const Foo1 = koffi.struct('Foo1', {
    i: 'int',
    a16: koffi.array('int16_t', 2)
});
const Foo2 = koffi.struct('Foo2', {
    i: 'int',
    a16: koffi.array('int16_t', 2, 'Array')
});

// Uses an hypothetical C function that just returns the struct passed as a parameter
const ReturnFoo1 = lib.func('Foo1 ReturnFoo(Foo1 p)');
const ReturnFoo2 = lib.func('Foo2 ReturnFoo(Foo2 p)');

console.log(ReturnFoo1({ i: 5, a16: [6, 8] })) // Prints { i: 5, a16: Int16Array(2) [6, 8] }
console.log(ReturnFoo2({ i: 5, a16: [6, 8] })) // Prints { i: 5, a16: [6, 8] }
```

--------------------------------

### Run tests on specific machines

Source: https://koffi.dev/contribute

Run the full test cycle on specific machines, or separate start, test, and shutdown steps.

```sh
# Full test cycle
node tools/brew.js test debian_x64 debian_i386

# Separate start, test, shutdown
node tools/brew.js start debian_x64 debian_i386
node tools/brew.js test debian_x64 debian_i386
node tools/brew.js stop
```

--------------------------------

### Flexible array C example

Source: https://koffi.dev/composites

C source for a flexible array API that appends values to a struct with a flexible array member. Build with clang as shown in the comment.

```C
// Build with: clang -fPIC -o flexible.so -shared flexible.c -Wall -O2

#include <stddef.h>

struct FlexibleArray {
    size_t count;
    int numbers[];
};

void AppendValues(struct FlexibleArray *arr, size_t count, int start, int step)
{
    for (size_t i = 0; i < count; i++) {
        arr->numbers[arr->count + i] = start + i * step;
    }
    arr->count += count;
}
```

--------------------------------

### Transient Callback Example (JavaScript)

Source: https://koffi.dev/callbacks

JavaScript code that loads a library, defines a callback prototype, and calls a C function with a transient callback. The callback is only valid during the call and prints the received values.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

const lib = koffi.load('./callbacks.so'); // Fake path

const TransferCallback = koffi.proto('int TransferCallback(const char *str, int age)');

const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);

let ret = TransferToJS('Niels', 27, (str, age) => {
    console.log(str);
    console.log('Your age is:', age);
    return 42;
});
console.log(ret);

// This example prints:
//   Hello Niels!
//   Your age is: 27
//   42

```

--------------------------------

### Transient Callback Example (C)

Source: https://koffi.dev/callbacks

C function that invokes a callback during its execution. The callback is passed as a function pointer and called with a formatted string and an age value.

```c
#include <string.h>

int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
{
    char buf[64];
    snprintf(buf, sizeof(buf), "Hello %s!", str);
    return cb(buf, age);
}

```

--------------------------------

### Win32 struct example with GetLastInputInfo

Source: https://koffi.dev/output

Calls the Win32 GetLastInputInfo() function. Defines the LASTINPUTINFO struct with a cbSize member, uses _Inout_ to copy the size from JS to C, and logs the result.

```JavaScript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

const user32 = koffi.load('user32.dll');

const LASTINPUTINFO = koffi.struct('LASTINPUTINFO', {
    cbSize: 'uint',
    dwTime: 'uint32'
});
const GetLastInputInfo = user32.func('bool __stdcall GetLastInputInfo(_Inout_ LASTINPUTINFO *plii)');

let info = { cbSize: koffi.sizeof(LASTINPUTINFO) };
let success = GetLastInputInfo(info);

console.log(success, info);
```

--------------------------------

### Opaque type example with SQLite

Source: https://koffi.dev/output

Opens an in-memory SQLite database using node-ffi-style function declaration syntax. Defines an opaque sqlite3 type, uses koffi.out() on a double pointer to copy out the database handle, and closes it.

```JavaScript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

const lib = koffi.load('sqlite3.so');

const sqlite3 = koffi.opaque('sqlite3');

// Use koffi.out() on a double pointer to copy out (from C to JS) after the call
const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['str', koffi.out(koffi.pointer(sqlite3, 2)), 'int', 'str']);
const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [koffi.pointer(sqlite3)]);

const SQLITE_OPEN_READWRITE = 0x2;
const SQLITE_OPEN_CREATE = 0x4;

let out = [null];
if (sqlite3_open_v2(':memory:', out, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
    throw new Error('Failed to open database');
let db = out[0];

sqlite3_close_v2(db);
```

--------------------------------

### Registered Callback Example (JavaScript)

Source: https://koffi.dev/callbacks

JavaScript code that registers callbacks with koffi.register, passes them to a C function, and unregisters them after use. Note the maximum of 8192 simultaneous registered callbacks and the need to unregister to avoid leaking slots.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

const lib = koffi.load('./callbacks.so'); // Fake path

const GetCallback = koffi.proto('const char *GetCallback(const char *name)');
const PrintCallback = koffi.proto('void PrintCallback(const char *str)');

const RegisterFunctions = lib.func('void RegisterFunctions(GetCallback *cb1, PrintCallback *cb2)');
const SayIt = lib.func('void SayIt(const char *name)');

let cb1 = koffi.register(name => 'Hello ' + name + '!', koffi.pointer(GetCallback));
let cb2 = koffi.register(console.log, 'PrintCallback *');

RegisterFunctions(cb1, cb2);
SayIt('Kyoto'); // Prints Hello Kyoto!

koffi.unregister(cb1);
koffi.unregister(cb2);

```

--------------------------------

### Passing union values to C with koffi.Union

Source: https://koffi.dev/composites

Shows how to create union instances with koffi.Union(type), set members with the dot operator, and pass them to a C function. The example defines a union U with int and char* members and calls DoSomething with each.

```javascript
const U = koffi.union('U', { i: 'int', str: 'char *' });

const DoSomething = lib.func('void DoSomething(const char *type, U u)');

const u1 = new koffi.Union('U'); u1.i = 42;
const u2 = new koffi.Union('U'); u2.str = 'Hello!';

DoSomething('int', u1);
DoSomething('string', u2);
```

--------------------------------

### Publish a new Koffi release

Source: https://koffi.dev/contribute

Run these commands from the src/koffi directory to test and build the brew tools, then prepare and publish the packages. Some platforms are emulated, so this can take a few minutes.

```sh
cd src/koffi

node tools/brew.js test # If not done before
node tools/brew.js build

cd ../../bin/Koffi/packages

./prepare.sh
./publish.sh
```

--------------------------------

### Build Koffi and benchmark with Clang

Source: https://koffi.dev/benchmarks

Commands to build Koffi and the benchmark using cnoke with Clang in release mode. Run from the src/koffi directory.

```sh
cd src/koffi
node ../cnoke/cnoke.js --clang --release

cd benchmark
node ../../cnoke/cnoke.js --clang --release
```

--------------------------------

### Passing union values to C with object literals

Source: https://koffi.dev/composites

Shows the simplified alternative to the previous example: Koffi accepts object literals with exactly one property to set the corresponding union member. The example passes { i: 42 } and { str: 'Hello!' } directly to DoSomething.

```javascript
const U = koffi.union('U', { i: 'int', str: 'char *' });

const DoSomething = lib.func('void DoSomething(const char *type, U u)');

DoSomething('int', { i: 42 });
DoSomething('string', { str: 'Hello!' });
```

--------------------------------

### Build and run tests locally

Source: https://koffi.dev/contribute

Run these commands from the src/koffi/test directory to build the C test code and run the test suite.

```sh
cd src/koffi/test
node ../../cnoke/cnoke.js # Build C test code
node test.js
```

--------------------------------

### Download Windows QEMU machine

Source: https://koffi.dev/contribute

Downloads and extracts the Windows x64 QEMU machine image from the provided URL. Run from tools/cross/.

```sh
cd tools/cross/
wget -q -O- https://download.koromix.dev/qemu/qemu_windows_x64.tar.zst | zstd -d | tar xv
```

--------------------------------

### koffi.introspect() usage

Source: https://koffi.dev/migration

Shows how to get struct members with koffi.introspect() in both Koffi 1.x and 2.x.

```javascript
const StructType = koffi.struct('StructType', { dummy: 'int' });

// Koffi 1.x
let members = koffi.introspect(StructType);

// Koffi 2.x
let members = koffi.introspect(StructType).members;
```

--------------------------------

### Run benchmark.js

Source: https://koffi.dev/benchmarks

Command to run the benchmark script after building.

```sh
node benchmark.js
```

--------------------------------

### Call a declared native function

Source: https://koffi.dev/load

Calls a declared native function (atoi) and logs the result type. This example shows that the return value is a number.

```javascript
let value = atoi('1257'); // Returns 1257 as number
console.log(typeof value); // Print number
```

--------------------------------

### Get Koffi configuration with koffi.config()

Source: https://koffi.dev/misc

Retrieves the current Koffi settings object, including memory block sizes. Use koffi.config(obj) to apply new settings.

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

--------------------------------

### Create Debian ARM64 machine

Source: https://koffi.dev/contribute

Use the build script to create the Debian ARM64 virtual machine. Run from tools/cross/build.

```sh
cd tools/cross/build
./debian_arm64/build.sh
```

--------------------------------

### Run tests on virtual machines

Source: https://koffi.dev/contribute

Run the test suite on all available machines using brew.js. Several options are available; use --help for details.

```sh
cd src/koffi

node tools/brew.js test # Several options are available, use --help
```

--------------------------------

### Load Koffi in JavaScript

Source: https://koffi.dev/start

Shows how to import Koffi using ES6 modules or CommonJS syntax.

```js
// ES6 modules
import koffi from 'koffi';

// CommonJS syntax
const koffi = require('koffi');
```

--------------------------------

### Specify explicit enum storage type

Source: https://koffi.dev/primitives

Shows how to pass an explicit type as the last argument to koffi.enumeration. This example uses int64_t even though the values fit in an int.

```javascript
// This one explictly uses int64_t as the underlying type, despite the fact that the values fit inside an int.
const ExplicitEnum = koffi.enumeration('ExplicitEnum', {
    Zero: 0,
    One: 1,
    Two: 2
}, 'int64_t');
```

--------------------------------

### Koffi 1.x opaque handle output parameter

Source: https://koffi.dev/migration

Shows how output parameters for opaque handles were handled in Koffi 1.x, using a plain object.

```javascript
// Koffi 1.x

const sqlite3 = koffi.handle('sqlite3');

const sqlite3_open_v2 = lib.func('int sqlite3_open_v2(const char *, _Out_ sqlite3 *db, int, const char *)');
const sqlite3_close_v2 = lib.func('int sqlite3_close_v2(sqlite3 db)');

const SQLITE_OPEN_READWRITE = 0x2;
const SQLITE_OPEN_CREATE = 0x4;

let db = {};

if (sqlite3_open_v2(':memory:', db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
    throw new Error('Failed to open database');

sqlite3_close_v2(db);
```

--------------------------------

### Use koffi.sizeof with type string and type object

Source: https://koffi.dev/types

Shows two equivalent ways to get the size of a primitive type: using the type string 'long' or the type object koffi.types.long.

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

--------------------------------

### JavaScript lookup of exported symbols with lib.symbol()

Source: https://koffi.dev/load

Uses lib.symbol() to get pointers to the exported variables. Returns a BigInt in Koffi 3. The type parameter is deprecated since Koffi 3.1.0.

```javascript
const my_int = lib.symbol('my_int');
const my_string = lib.symbol('my_string');
```

--------------------------------

### Koffi 1.x callback usage

Source: https://koffi.dev/migration

Shows how callbacks were defined and used in Koffi 1.x, directly as parameter type.

```javascript
// Koffi 1.x

const TransferCallback = koffi.proto('int TransferCallback(const char *str, int age)');

const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', TransferCallback]);
// Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback cb)');

let ret = TransferToJS('Niels', 27, (str, age) => {
    console.log(str);
    console.log('Your age is:', age);
    return 42;
});
console.log(ret);
```

--------------------------------

### Declare and call variadic functions with printf

Source: https://koffi.dev/load

Shows two equivalent ways to declare a variadic function (printf) and how to call it by providing type-value pairs for each variadic argument. On x86 platforms, only the Cdecl convention can be used for variadic functions.

```javascript
// These two declarations are identical
const printf1 = lib.func('printf', 'int', ['str', '...']);
const printf2 = lib.func('int printf(str fmt, ...)');

// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
printf1('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
printf2('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
```

--------------------------------

### Load a shared library with koffi.load()

Source: https://koffi.dev/load

Loads a shared library using koffi.load(). The file extension depends on the platform (.so, .dll, .dylib). The library is automatically unloaded when all references are gone.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

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

--------------------------------

### POSIX struct example with gettimeofday

Source: https://koffi.dev/output

Calls the POSIX gettimeofday() function using prototype-like syntax. Defines timeval and timezone structs, uses _Out_ qualifiers to marshal out values, and logs the result.

```JavaScript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

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

const timeval = koffi.struct('timeval', {
    tv_sec: 'unsigned int',
    tv_usec: 'unsigned int'
});
const timezone = koffi.struct('timezone', {
    tz_minuteswest: 'int',
    tz_dsttime: 'int'
});

// The _Out_ qualifiers instruct Koffi to marshal out the values
const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');

let tv = {};
gettimeofday(tv, null);

console.log(tv);
```

--------------------------------

### Use '!' shortcut qualifier in prototype-like syntax

Source: https://koffi.dev/pointers

Shows how to use the '!' qualifier to create an anonymous disposable type that calls koffi.free(ptr) in prototype-like syntax. The commented alternative shows the equivalent explicit form.

```javascript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

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

// You can also use: const strdup = lib.func('const char *! strdup(const char *str)')
const strdup = lib.func('str! strdup(const char *str)');

let copy = strdup('World!');
console.log(copy); // Prints World!
```

--------------------------------

### Check POSIX errno with koffi.errno() and koffi.os.errno

Source: https://koffi.dev/misc

Demonstrates using koffi.errno() to get the current errno value and comparing it to koffi.os.errno.EBADF after a failed close() call. Requires loading libc.so.6 and defining the close function.

```JavaScript
const assert = require('assert');

import koffi from 'koffi';
// CJS: 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!');
```

--------------------------------

### Using struct types in function declarations

Source: https://koffi.dev/composites

Once a struct is declared, you can use it by name (as a string) or through the value returned by koffi.struct(). This example shows two equivalent ways to declare a function that takes and returns a struct.

```APIDOC
## Using struct types in function declarations

### Description
Once a struct is declared, you can use it by name (as a string) or through the value returned by koffi.struct(). This example shows two equivalent ways to declare a function that takes and returns a struct.

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

### Notes
- Only the returned value can be used for anonymous structs.
```

--------------------------------

### lib.func(name, returnType, parameters) - Classic syntax

Source: https://koffi.dev/load

Declares a native function using the classic node-ffi inspired syntax. The function can then be called as a regular JavaScript function.

```APIDOC
## lib.func(name, returnType, parameters)

### Description
Declares a native function from the loaded library using the classic syntax. The function is identified by its non-mangled name. The return type and parameter types are specified as strings. For variadic functions, use an ellipsis as the last parameter.

### Method
func

### Parameters
#### Path Parameters
- **name** (string) - Required - Non-mangled name of the function.
- **returnType** (string) - Required - Return type of the function (e.g., 'int').
- **parameters** (array) - Required - Array of parameter type strings (e.g., ['str']). Use an ellipsis as the last parameter for variadic functions.

### Request Example
```js
const atoi = lib.func('atoi', 'int', ['str']);
```

### Response
#### Success Response
Returns a JavaScript function that can be called with the declared parameters.

### Usage Example
```js
let value = atoi('1257'); // Returns 1257 as number
console.log(typeof value); // Print number
```

### Notes
- Koffi automatically tries mangled names for non-standard x86 calling conventions.
```

--------------------------------

### GetCursorPos struct pointer example

Source: https://koffi.dev/pointers

Uses Koffi to call the Win32 GetCursorPos function with an output struct pointer. Requires user32.dll and defines a POINT struct with long fields. Throws an error if the call fails.

```JavaScript
import koffi from 'koffi';
// CJS: const koffi = require('koffi');

const lib = koffi.load('user32.dll');

// Type declarations
const POINT = koffi.struct('POINT', {
    x: 'long',
    y: 'long'
});

// Functions declarations
const GetCursorPos = lib.func('int __stdcall GetCursorPos(_Out_ POINT *pos)');

// Get and show cursor position
let pos = {};
if (!GetCursorPos(pos))
    throw new Error('Failed to get cursor position');
console.log(pos);
```
Tokens:
Raw