koffi 3.0.1 → 3.1.0

package/doc/{functions.md → load.md}

@@ -11,14 +11,7 @@ const lib = koffi.load('/path/to/shared/library'); // File extension depends on
 
 This library will be automatically unloaded once all references to it are gone (including all the functions that use it, as described below).
 
-Starting with *Koffi 2.3.20*, you can explicitly unload a library by calling `lib.unload()`. Any attempt to find or call a function from this library after unloading it will crash.
-
-> [!NOTE]
-> On some platforms (such as with the [musl C library on Linux](https://wiki.musl-libc.org/functional-differences-from-glibc.html#Unloading-libraries)), shared libraries cannot be unloaded, so the library will remain loaded and memory mapped after the call to `lib.unload()`.
-
-# Loading options
-
-*New in Koffi 2.6, changed in Koffi 2.8.2 and Koffi 2.8.6*
+## Load options
 
 The `load` function can take an optional object argument, with the following options:
 
@@ -34,7 +27,14 @@ const lib = koffi.load('/path/to/shared/library.so', options);
 
 More options may be added if needed.
 
-# Function definitions
+## Unloading
+
+Use `lib.unload()` to can explicitly unload a library. Any attempt to find or call a function from this library after unloading it will crash.
+
+> [!NOTE]
+> On some platforms (such as with the [musl C library on Linux](https://wiki.musl-libc.org/functional-differences-from-glibc.html#Unloading-libraries)), shared libraries cannot be unloaded, so the library will remain loaded and memory mapped after the call to `lib.unload()`.
+
+# Functions
 
 ## Definition syntax
 
@@ -48,10 +48,16 @@ Use the object returned by `koffi.load()` to load C functions from the library.
 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.
 
 ```js
-const printf = lib.func('printf', 'int', ['str', '...']);
 const atoi = lib.func('atoi', 'int', ['str']);
 ```
 
+Once a native function has been declared, you can simply call it as you would any other JS function:
+
+```js
+let value = atoi('1257'); // Returns 1257 as number
+console.log(typeof value); // Print number
+```
+
 Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section on [calling conventions](#calling-conventions) for more information on this subject.
 
 ### C-like prototypes
@@ -59,8 +65,15 @@ Koffi automatically tries mangled names for non-standard x86 calling conventions
 If you prefer, you can declare functions using simple C-like prototype strings, as shown below:
 
 ```js
-const printf = lib.func('int printf(const char *fmt, ...)');
-const atoi = lib.func('int atoi(str)'); // The parameter name is not used by Koffi, and optional
+// The parameter name (nptn below) is not used by Koffi, and optional, but can be nice for documentation
+const atoi = lib.func('int atoi(const char *nptr)');
+```
+
+Once a native function has been declared, you can simply call it as you would any other JS function:
+
+```js
+let value = atoi('1257'); // Returns 1257 as number
+console.log(typeof value); // Print number
 ```
 
 You can use `()` or `(void)` for functions that take no argument.
@@ -72,20 +85,19 @@ 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.
 
 ```js
-const printf = lib.func('printf', 'int', ['str', '...']);
+// 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 *)
-printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
+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');
 ```
 
 On x86 platforms, only the Cdecl convention can be used for variadic functions.
 
 ## Calling conventions
 
-*Changed in Koffi 2.7*
-
-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
@@ -97,11 +109,6 @@ Most architectures only support one procedure call standard per process. The 32-
 
 You can safely use these on non-x86 platforms, they are simply ignored.
 
-> [!NOTE]
-> Support for specifying the convention as the first argument of the classic form was introduced in Koffi 2.7.
->
-> In earlier versions, you had to use `koffi.stdcall()` and similar functions. These functions are still supported but deprecated, and will be removed in Koffi 3.0.
-
 Below you can find a small example showing how to use a non-default calling convention, with the two syntaxes:
 
 ```js
@@ -111,30 +118,8 @@ import koffi from 'koffi';
 const lib = koffi.load('user32.dll');
 
 // The following two declarations are equivalent, and use stdcall on x86 (and the default ABI on other platforms)
-const MessageBoxA_1 = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
-const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');
-```
-
-# Call types
-
-## Synchronous calls
-
-Once a native function has been declared, you can simply call it as you would any other JS function.
-
-```js
-const atoi = lib.func('int atoi(const char *str)');
-
-let value = atoi('1257');
-console.log(value);
-```
-
-For [variadic functions](functions#variadic-functions), you msut specificy the type and the value for each additional argument.
-
-```js
-const printf = lib.func('printf', 'int', ['str', '...']);
-
-// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
-printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
+const MessageBoxA1 = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
+const MessageBoxA2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');
 ```
 
 ## Asynchronous calls
@@ -167,84 +152,40 @@ Variadic functions cannot be called asynchronously.
 
 > [!WARNING]
 > 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!
-
-# Function pointers
-
-*New in Koffi 2.4*
-
-You can call a function pointer in two ways:
 
-- Directly call the function pointer with `koffi.call(ptr, type, ...)`
-- Decode the function pointer to an actual function with `koffi.decode(ptr, type)`
+## Conversion of parameters
 
-The example below shows how to call an `int (*)(int, int)` C function pointer both ways, based on the following native C library:
-
-```c
-typedef int BinaryIntFunc(int a, int b);
-
-static int AddInt(int a, int b) { return a + b; }
-static int SubstractInt(int a, int b) { return a - b; }
-
-BinaryIntFunc *GetBinaryIntFunction(const char *type)
-{
-    if (!strcmp(type, "add")) {
-        return AddInt;
-    } else if (!strcmp(type, "substract")) {
-        return SubstractInt;
-    } else {
-        return NULL;
-    }
-}
-```
-
-## Call pointer directly
+By default, Koffi will only forward and translate arguments from Javascript to C. However, many C functions use pointer arguments for output values, or input/output values.
 
-Use `koffi.call(ptr, type, ...)` to call a function pointer. The first two arguments are the pointer itself and the type of the function you are trying to call (declared with `koffi.proto()` as shown below), and the remaining arguments are used for the call.
+Among other thing, in the the following pages you will learn more about:
 
-```js
-// Declare function type
-const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
+- The [primitives types](primitives) supported by Koffi
+- How to define [composite types](composites): structs, arrays and unions
+- How you can [define and use pointers](pointers)
+- How to deal with [output parameters](output)
 
-const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
+# Variables
 
-const add_ptr = GetBinaryIntFunction('add');
-const substract_ptr = GetBinaryIntFunction('substract');
+*Changed in Koffi 3.1.0*
 
-let sum = koffi.call(add_ptr, BinaryIntFunc, 4, 5);
-let delta = koffi.call(substract_ptr, BinaryIntFunc, 100, 58);
+To find an exported variable symbol, use `lib.symbol(name)`. You need to specify its name and its type.
 
-console.log(sum, delta); // Prints 9 and 42
+```c
+int my_int = 42;
+const char *my_string = NULL;
 ```
 
-## Decode pointer to function
-
-Use `koffi.decode(ptr, type)` to get back a JS function, which you can then use like any other Koffi function.
-
-This method also allows you to perform an [asynchronous call](#asynchronous-calls) with the async member of the decoded function.
-
 ```js
-// Declare function type
-const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
-
-const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
-
-const add = koffi.decode(GetBinaryIntFunction('add'), BinaryIntFunc);
-const substract = koffi.decode(GetBinaryIntFunction('substract'), BinaryIntFunc);
-
-let sum = add(4, 5);
-let delta = substract(100, 58);
-
-console.log(sum, delta); // Prints 9 and 42
+const my_int = lib.symbol('my_int');
+const my_string = lib.symbol('my_string');
 ```
 
-# Conversion of parameters
-
-By default, Koffi will only forward and translate arguments from Javascript to C. However, many C functions use pointer arguments for output values, or input/output values.
+This function returns a pointer (a BigInt value in Koffi 3). To read or change the value of the variable, you can use:
 
-Among other thing, in the the following pages you will learn more about:
+- [koffi.decode()](values#decode-to-js-values) to read the value
+- [koffi.encode()](values#encode-to-c-memory) to change the value
 
-- How Koffi translates [input parameters](input) to C
-- How you can [define and use pointers](pointers)
-- How to deal with [output parameters](output)
+> [!NOTE]
+> Until Koffi 3.1.0, the `symbol()` function required you to give a type, even though it did nothing with this information. This was a leftover from Koffi 2.
+> 
+> For compatibility, you can still call `lib.symbol(name, type)`, but this is deprecated.

package/doc/migration.md

@@ -6,7 +6,7 @@ However, some changes could impact your code:
 
 - Koffi is now distributed in [split packages](#split-packages) to reduce install size/bloat.
 - Pointers are now [BigInt values](#bigint-pointers) instead of opaque V8 external values.
-- Types created by koffi are now [type objects](#type-objects) insted of opaque V8 external values.
+- Types created by koffi are now [type objects](#type-objects) instead of opaque V8 external values.
 - Using `koffi.register()` with a [receiver value](#registered-callback-binding) is deprecated.
 - Several old [deprecated functions](#removed-functions) have been removed.
 
@@ -36,7 +36,7 @@ You can resolve type strings to type objects with `koffi.type()`. This function
 > [!NOTE]
 > For compatibility reasons, both `koffi.resolve()` and `koffi.introspect()` still exist, as aliases for `koffi.type()`. Using them will emit a deprecation warning.
 
-Read the documentation about [type specifiers](migration#type-specifiers) for more information.
+Read the documentation about [type specifiers](types#type-specifiers) for more information.
 
 The two versions below illustrate the API difference between Koffi 2.x and Koffi 3.x:
 
@@ -108,7 +108,7 @@ You may need to change your code if you use:
 - Opaque types
 - `koffi.introspect()`
 
-## Callback type changes
+## Callback types
 
 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.
 
@@ -161,10 +161,7 @@ console.log(ret);
 
 Koffi 1.x only supported [transient callbacks](callbacks#javascript-callbacks), you must use Koffi 2.x for registered callbacks.
 
-> [!NOTE]
-> The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
-
-## Opaque type changes
+## Opaque types
 
 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, in Koffi 2.0, you must use them through a pointer, and use an array for output parameters.
 

package/doc/misc.md

@@ -1,98 +1,3 @@
-# Types
-
-## Type specifiers
-
-*Changed in Koffi 3.0*
-
-> [!NOTE]
-> In Koffi 2.0, types were External values, you had to use `koffi.introspect()` to get type information. In Koffi 3.0, this information is directly available in type objects, and this function is deprecated.
->
-> Consult the [migration guide](migration) for more information.
-
-You can use strings or type objects to give type information to Koffi (when declaring functions, structs, and so on). Use `koffi.type(spec)` to resolve all accepted type values (strings and type objects) to type objects.
-
-You can inspect the type object for information: name, primitive, size, alignment, members (record types), reference type (array, pointer), length (array), arguments and return type (prototypes).
-
-```js
-const FoobarType = koffi.struct('FoobarType', {
-    a: 'int',
-    b: 'char *',
-    c: 'double'
-});
-
-console.log(FoobarType);
-
-// Expected result on 64-bit machines:
-// {
-//     name: 'FoobarType',
-//     primitive: 'Record',
-//     size: 24,
-//     alignment: 8,
-//     disposable: false,
-//     members: {
-//         a: { name: 'a', type: [Type], offset: 0 },
-//         b: { name: 'b', type: [Type], offset: 8 },
-//         c: { name: 'c', type: [Type], 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.type(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`:
-
-```js
-// 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.
-
-## Circular references
-
-*New in Koffi 2.10.0*
-
-In some cases, composite types can point to each other and thus depend on each other. This can also happen when a function takes a pointer to a struct that also contains a function pointer.
-
-To deal with this, you can create an opaque type and redefine it later to a concrete struct or union type, as shown below.
-
-```js
-const Type1 = koffi.opaque('Type1');
-
-const Type2 = koffi.struct('Type2', {
-    ptr: 'Type1 *',
-    i: 'int'
-});
-
-// Redefine Type1 to a concrete type
-koffi.struct(Type1, {
-    ptr: 'Type2 *',
-    f: 'float'
-});
-```
-
-> [!NOTE]
-> You must use a proper type object when you redefine the type. If you only have the name, use `koffi.resolve()` to get a type object from a type string.
->
-> ```js
-> const MyType = koffi.opaque('MyType');
->
-> // This does not work, you must use the MyType object and not a type string
-> koffi.struct('MyType', {
->      ptr: 'Type2 *',
->      f: 'float'
-> });
-
 # Settings
 
 ## Memory usage
@@ -122,8 +27,6 @@ Async calls run on worker threads, the number of which depends on the number of
 
 ## Default settings
 
-*Changed in Koffi 2.15*
-
 Setting              | Default | Maximum | Description
 -------------------- | ------- | ------- | ----------------------------------------------------
 sync_stack_size      | 1 MiB   | 16 MiB  | Stack size for synchronous calls
@@ -136,14 +39,10 @@ max_type_size        | 64 MiB  | 512 MiB | Maximum size of Koffi types (for arra
 
 # 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:
@@ -166,8 +65,6 @@ 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

package/doc/output.md

@@ -2,9 +2,9 @@
 
 For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) multiple types of parameters:
 
-- [Structs](input#struct-types) (to/from JS objects)
-- [Unions](unions)
-- [Opaque types](input#opaque-types)
+- [Structs](composites#structs) (to/from JS objects)
+- [Unions](composites#unions)
+- [Opaque types](composites#opaque-types)
 - String buffers
 
 In order to change an argument from input-only to output or input/output, use the following functions:
@@ -161,8 +161,6 @@ sqlite3_close_v2(db);
 
 ## String buffer example
 
-*New in Koffi 2.2*
-
 This example calls a C function to concatenate two strings to a pre-allocated string buffer. Since JS strings are immutable, you must pass an array with a single string instead.
 
 ```c
@@ -208,8 +206,6 @@ In most cases, you can use buffers and typed arrays to provide output buffers. T
 
 ## Transient pointers
 
-*New in Koffi 2.3*
-
 You can use buffers and typed arrays for output (and input/output) pointer parameters. Simply pass the buffer as an argument and the native function will receive a pointer to its contents.
 
 Once the native function returns, you can decode the content with `koffi.decode(value, type)` as in the following example:
@@ -248,17 +244,15 @@ console.log(vec1); // { x: 3, y: 2, z: 1 }
 console.log(vec2); // { x: 1, y: 2, z: 3 }
 ```
 
-See [decoding variables](variables#decode-to-js-values) for more information about the decode function.
+See [decoding variables](values#decode-to-js-values) for more information about the decode function.
 
 ## Stable pointers
 
-*New in Koffi 2.8*
-
 In some cases, the native code may need to change the output buffer at a later time, maybe during a later call or from another thread.
 
 In this case, it is **not safe to use buffers or typed arrays**! 
 
-However, you can use `koffi.alloc(type, len)` to allocate memory and get a pointer that won't move, and can be safely used at any time by the native code. Use [koffi.decode()](variables#decode-to-js-values) to read data from the pointer when needed.
+However, you can use `koffi.alloc(type, len)` to allocate memory and get a pointer that won't move, and can be safely used at any time by the native code. Use [koffi.decode()](values#decode-to-js-values) to read data from the pointer when needed.
 
 The example below sets up some memory to be used as an output buffer where a concatenation function appends a string on each call.
 

package/doc/pointers.md

@@ -5,13 +5,15 @@ In C, pointer arguments are used for differenty purposes. It is important to dis
 - **Struct pointers**: Use of struct pointers by C libraries fall in two cases: avoid (potentially) expensive copies, and to let the function change struct contents (output or input/output arguments).
 - **Opaque pointers**: the library does not expose the contents of the structs, and only provides you with a pointer to it (e.g. `FILE *`). Only the functions provided by the library can do something with this pointer, in Koffi we call this an opaque type. This is usually done for ABI-stability reason, and to prevent library users from messing directly with library internals.
 - **Pointers to primitive types**: This is more rare, and generally used for output or input/output arguments. The Win32 API has a lot of these.
-- **Arrays**: in C, you dynamically-sized arrays are usually passed to functions with pointers, either NULL-terminated (or any other sentinel value) or with an additional length argument.
+- **Arrays**: in C, dynamically-sized arrays are usually passed to functions with pointers, either NULL-terminated (or any other sentinel value) or with an additional length argument.
 
-# Pointer types
+Koffi uses BigInt numbers to represent pointers.
+
+# Data pointers
 
 ## Struct pointers
 
-The following Win32 example uses `GetCursorPos()` (with an output parameter) to retrieve and show the current cursor position.
+The following Win32 example uses `GetCursorPos()` (with an [output parameter](output)) to retrieve and show the current cursor position.
 
 ```js
 import koffi from 'koffi';
@@ -37,8 +39,6 @@ console.log(pos);
 
 ## Opaque pointers
 
-*New in Koffi 2.0*
-
 Some C libraries use handles, which behave as pointers to opaque structs. An example of this is the HANDLE type in the Win32 API. If you want to reproduce this behavior, you can define a **named pointer type** to an opaque type, like so:
 
 ```js
@@ -49,11 +49,9 @@ const GetHandleInformation = lib.func('bool __stdcall GetHandleInformation(HANDL
 const CloseHandle = lib.func('bool __stdcall CloseHandle(HANDLE h)');
 ```
 
-Koffi uses BigInt numbers to represent opaque pointers.
-
 ## Pointer to primitive types
 
-In javascript, it is not possible to pass a primitive value by reference to another function. This means that you cannot call a function and expect it to modify the value of one of its number or string parameter.
+In Javascript, it is not possible to pass a primitive value by reference to another function. This means that you cannot call a function and expect it to modify the value of one of its number or string parameter.
 
 However, arrays and objects (among others) are reference type values. Assigning an array or an object from one variable to another does not invole any copy. Instead, as the following example illustrates, the new variable references the same array as the first:
 
@@ -68,7 +66,7 @@ console.log(list1); // Prints [1, 42]
 
 All of this means that C functions that are expected to modify their primitive output values (such as an `int *` parameter) cannot be used directly. However, thanks to Koffi's transparent array support, you can use Javascript arrays to approximate reference semantics with single-element arrays.
 
-Below, you can find an example of an addition function where the result is stored in an `int *` input/output parameter and how to use this function from Koffi.
+Below, you can find an example of an addition function where the result is stored in an `int *` [input/output parameter](output) and how to use this function from Koffi.
 
 ```c
 void AddInt(int *dest, int add)
@@ -132,9 +130,74 @@ console.log(total); // Prints 14
 
 By default, just like for objects, array arguments are copied from JS to C but not vice-versa. You can however change the direction as documented in the section on [output parameters](output).
 
-# Handling void pointers
+# Function pointers
+
+You can call a function pointer in two ways:
+
+- Directly call the function pointer with `koffi.call(ptr, type, ...)`
+- Decode the function pointer to an actual function with `koffi.decode(ptr, type)`
+
+The example below shows how to call an `int (*)(int, int)` C function pointer both ways, based on the following native C library:
+
+```c
+typedef int BinaryIntFunc(int a, int b);
+
+static int AddInt(int a, int b) { return a + b; }
+static int SubstractInt(int a, int b) { return a - b; }
+
+BinaryIntFunc *GetBinaryIntFunction(const char *type)
+{
+    if (!strcmp(type, "add")) {
+        return AddInt;
+    } else if (!strcmp(type, "substract")) {
+        return SubstractInt;
+    } else {
+        return NULL;
+    }
+}
+```
+
+## Call pointer directly
+
+Use `koffi.call(ptr, type, ...)` to call a function pointer. The first two arguments are the pointer itself and the type of the function you are trying to call (declared with `koffi.proto()` as shown below), and the remaining arguments are used for the call.
+
+```js
+// Declare function type
+const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
 
-*New in Koffi 2.1*
+const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
+
+const add_ptr = GetBinaryIntFunction('add');
+const substract_ptr = GetBinaryIntFunction('substract');
+
+let sum = koffi.call(add_ptr, BinaryIntFunc, 4, 5);
+let delta = koffi.call(substract_ptr, BinaryIntFunc, 100, 58);
+
+console.log(sum, delta); // Prints 9 and 42
+```
+
+## Decode pointer to function
+
+Use `koffi.decode(ptr, type)` to get back a JS function, which you can then use like any other Koffi function.
+
+```js
+// Declare function type
+const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
+
+const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
+
+const add = koffi.decode(GetBinaryIntFunction('add'), BinaryIntFunc);
+const substract = koffi.decode(GetBinaryIntFunction('substract'), BinaryIntFunc);
+
+let sum = add(4, 5);
+let delta = substract(100, 58);
+
+console.log(sum, delta); // Prints 9 and 42
+```
+
+This method also allows you to perform an [asynchronous call](load#asynchronous-calls) with the async member of the decoded function.
+
+# Handling void pointers
 
 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.
 
@@ -143,7 +206,7 @@ Koffi provides two features to deal with this:
 - You can use `koffi.as(value, type)` to tell Koffi what kind of type is actually expected, as shown in the example below.
 - Buffers and typed JS arrays can be used as values in place everywhere a pointer is expected. See [dynamic arrays](#dynamic-arrays) for more information, for input or output.
 
-The example below shows the use of `koffi.as()` to read the header of a PNG file with `fread()` directly to a JS object.
+The example below shows the use of `koffi.as()` to read the header of a PNG file with `fread()` directly to a JS object. It also uses [endian-sensitive integers](primitives#endian-sensitive-integers) to decode PNG header values:
 
 ```js
 import koffi from 'koffi';
@@ -197,8 +260,6 @@ console.log('PNG header:', hdr);
 
 # Disposable types
 
-*New in Koffi 2.0*
-
 Disposable types allow you to register a function that will automatically called after each C to JS conversion performed by Koffi. This can be used to avoid leaking heap-allocated strings, for example.
 
 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.
@@ -230,7 +291,7 @@ let copy = strdup('Hello!');
 console.log(copy); // Prints Hello!
 ```
 
-When you declare functions with the [prototype-like syntax](functions#definition-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)`.
+When you declare functions with the [prototype-like syntax](load#definition-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)`.
 
 ```js
 import koffi from 'koffi';
@@ -252,8 +313,6 @@ Disposable types can only be created from pointer or string types.
 
 # External buffers (views)
 
-*New in Koffi 2.11.0*
-
 You can access unmanaged memory with `koffi.view(ptr, len)`. This function takes a pointer and a length, and creates an ArrayBuffer through which you can access the underlying memory without copy.
 
 > [!NOTE]