koffi 2.9.1 → 2.10.0

package/doc/{contribute.md → pages/contribute.md}

@@ -1,12 +1,10 @@
-# Contributing
-
-## Bugs and feature requests
+# Bugs and feature requests
 
 Use the official repository for bugs, ideas and features requests: https://github.com/Koromix/koffi
 
 Please note that the source code is not in this repository, instead it lives in a monorepo: https://github.com/Koromix/rygel/ (in the *src/koffi* subdirectory).
 
-## Build from source
+# Build from source
 
 We provide prebuilt binaries, packaged in the NPM archive, so in most cases it should be as simple as `npm install koffi`. If you want to hack Koffi or use a specific platform, follow the instructions below.
 
@@ -19,7 +17,7 @@ cd rygel
 
 As said before, this is a monorepository containg multiple projects, hence the name.
 
-### Windows
+## Windows
 
 First, make sure the following dependencies are met:
 
@@ -34,7 +32,7 @@ cd src/koffi
 node ../cnoke/cnoke.js
 ```
 
-### Other platforms
+## Other platforms
 
 Make sure the following dependencies are met:
 
@@ -50,9 +48,9 @@ cd src/koffi
 node ../cnoke/cnoke.js
 ```
 
-## Run tests
+# Run tests
 
-### On your machine
+## On your machine
 
 Once Koffi is built, you can build the tests and run them with the following commands:
 
@@ -63,7 +61,7 @@ node ../../cnoke/cnoke.js
 node test.js
 ```
 
-### On virtual machines
+## On virtual machines
 
 Koffi is tested on multiple architectures using emulated (accelerated when possible) QEMU machines. First, you need to install qemu packages, such as `qemu-system` (or even `qemu-system-gui`) on Ubuntu.
 
@@ -121,12 +119,12 @@ Each machine is configured to run a VNC server available locally, which you can
 node qemu.js info debian_x64
 ```
 
-## Making a release
+# Making a release
 
 First, you must update the code in three steps:
 
 - Change the version numbers in `package.json` (version and stable for stable releases)
-- Add an entry to `CHANGELOG.md` to summarize the changes since last release
+- Add an entry to `CHANGELOG` to summarize the changes since last release
 - Commit theses changes with the message *Bump Koffi to X.Y.Z*
 
 Once this is done, you can publish a new release with the following commands:
@@ -141,7 +139,7 @@ npm publish
 
 Some platforms are emulated so this can take a few minutes until the pre-built binaries are ready. Go grab a cup of coffee, come back and execute the `npm publish` command!
 
-## Code style
+# Code style
 
 Koffi is programmed in a mix of C++ and assembly code (architecture-specific code). It uses [node-addon-api](https://github.com/nodejs/node-addon-api) (C++ N-API wrapper) to interact with Node.js.
 

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

@@ -1,6 +1,4 @@
-# Function calls
-
-## Loading libraries
+# Loading libraries
 
 To declare functions, start by loading the shared library with `koffi.load(filename)`.
 
@@ -15,11 +13,10 @@ This library will be automatically unloaded once all references to it are gone (
 
 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()`.
-```
+> [!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
+# Loading options
 
 *New in Koffi 2.6, changed in Koffi 2.8.2 and Koffi 2.8.6*
 
@@ -37,16 +34,16 @@ const lib = koffi.load('/path/to/shared/library.so', options);
 
 More options may be added if needed.
 
-## Function definitions
+# Function definitions
 
-### Definition syntax
+## Definition syntax
 
 Use the object returned by `koffi.load()` 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
+### 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.
 
@@ -57,7 +54,7 @@ const atoi = lib.func('atoi', 'int', ['str']);
 
 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
+### C-like prototypes
 
 If you prefer, you can declare functions using simple C-like prototype strings, as shown below:
 
@@ -68,7 +65,7 @@ const atoi = lib.func('int atoi(str)'); // The parameter name is not used by Kof
 
 You can use `()` or `(void)` for functions that take no argument.
 
-### Variadic functions
+## Variadic functions
 
 Variadic functions are declared with an ellipsis as the last argument.
 
@@ -83,7 +80,7 @@ printf('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
+## Calling conventions
 
 *Changed in Koffi 2.7*
 
@@ -100,11 +97,10 @@ 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.
-```
+> [!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:
 
@@ -119,9 +115,9 @@ const MessageBoxA_1 = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'st
 const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');
 ```
 
-## Call types
+# Call types
 
-### Synchronous calls
+## Synchronous calls
 
 Once a native function has been declared, you can simply call it as you would any other JS function.
 
@@ -132,7 +128,7 @@ let value = atoi('1257');
 console.log(value);
 ```
 
-For [variadic functions](functions.md#variadic-functions), you msut specificy the type and the value for each additional argument.
+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', '...']);
@@ -141,7 +137,7 @@ const printf = lib.func('printf', 'int', ['str', '...']);
 printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
 ```
 
-### Asynchronous calls
+## 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.
 
@@ -169,13 +165,12 @@ You can easily convert this callback-style async function to a promise-based ver
 
 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!
-```
+> [!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
+# Function pointers
 
 *New in Koffi 2.4*
 
@@ -204,7 +199,7 @@ BinaryIntFunc *GetBinaryIntFunction(const char *type)
 }
 ```
 
-### Call pointer directly
+## 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.
 
@@ -223,7 +218,7 @@ let delta = koffi.call(substract_ptr, BinaryIntFunc, 100, 58);
 console.log(sum, delta); // Prints 9 and 42
 ```
 
-### Decode pointer to function
+## 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.
 
@@ -244,12 +239,12 @@ let delta = substract(100, 58);
 console.log(sum, delta); // Prints 9 and 42
 ```
 
-## Conversion of parameters
+# 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.
 
 Among other thing, in the the following pages you will learn more about:
 
-- How Koffi translates [input parameters](input.md) to C
-- How you can [define and use pointers](pointers.md)
-- How to deal with [output parameters](output.md)
+- How Koffi translates [input parameters](input) to C
+- How you can [define and use pointers](pointers)
+- How to deal with [output parameters](output)

package/doc/pages/index.md

@@ -0,0 +1,20 @@
+# Koffi
+
+Koffi is a **fast and easy-to-use C FFI module for Node.js**, featuring:
+
+* Low-overhead and fast performance (see [benchmarks](benchmarks))
+* Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
+* Javascript functions can be used as C callbacks (since 1.2.0)
+* Well-tested code base for [popular OS/architecture combinations](platforms)
+
+Koffi requires a recent [Node.js](https://nodejs.org/) version with N-API version 8 support, see [this page](platforms) for more information.
+
+The source code is available here: https://github.com/Koromix/rygel/ (in the *src/koffi* subdirectory).
+
+New releases are frequent, look at the [changelog](changelog) for more information.
+
+# License
+
+This program is free software: you can redistribute it and/or modify it under the terms of the **MIT License**.
+
+Find more information here: https://choosealicense.com/licenses/mit/

package/doc/{input.md → pages/input.md}

@@ -1,8 +1,6 @@
-# Input parameters
+# Primitive types
 
-## Primitive types
-
-### Standard 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:
 
@@ -59,7 +57,7 @@ let struct1 = koffi.struct({ dummy: 'long' });
 let struct2 = koffi.struct({ dummy: koffi.types.long });
 ```
 
-### Endian-sensitive integers
+## Endian-sensitive integers
 
 *New in Koffi 2.1*
 
@@ -80,9 +78,9 @@ 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 types
 
-### Struct definition
+## Struct definition
 
 Koffi converts JS objects to C structs, and vice-versa.
 
@@ -141,23 +139,22 @@ const Function1 = lib.func('A Function(A value)');
 const Function2 = lib.func('Function', A, [A]);
 ```
 
-### Opaque types
+## 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](output.md) (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](output.md).
+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](output) (with a double pointer).
 
-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](migration.md) for more information.
-```
+> [!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](output).
+>
+> 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](migration) 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`.
 
@@ -335,9 +332,9 @@ try {
 }
 ```
 
-## Array types
+# Array types
 
-### Fixed-size C arrays
+## Fixed-size C arrays
 
 *Changed in Koffi 2.7.1*
 
@@ -381,11 +378,10 @@ const StructType = koffi.struct('StructType', {
 });
 ```
 
-```{note}
-The short C-like syntax was introduced in Koffi 2.7.1, use `koffi.array()` for older versions.
-```
+> [!NOTE]
+> The short C-like syntax was introduced in Koffi 2.7.1, use `koffi.array()` for older versions.
 
-### Fixed-size string buffers
+## Fixed-size string buffers
 
 *Changed in Koffi 2.9.0*
 
@@ -395,16 +391,15 @@ Koffi can also convert JS strings to fixed-sized arrays in the following cases:
 - **char16 (or char16_t) arrays** are filled with the UTF-16 encoded string, truncated if needed. The buffer is always NUL-terminated.
 - **char32 (or char32_t) arrays** are filled with the UTF-32 encoded string, truncated if needed. The buffer is always NUL-terminated.
 
-```{note}
-Support for UTF-32 and wchar_t (wide) strings was introduced in Koffi 2.9.0.
-```
+> [!NOTE]
+> Support for UTF-32 and wchar_t (wide) strings was introduced in Koffi 2.9.0.
 
 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_t and char32_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)
+## Dynamic arrays (pointers)
 
-In C, dynamically-sized arrays are usually passed around as pointers. Read more about [array pointers](pointers.md#dynamic-arrays) in the relevant section.
+In C, dynamically-sized arrays are usually passed around as pointers. Read more about [array pointers](pointers#dynamic-arrays) in the relevant section.
 
-## Union types
+# Union types
 
-The declaration and use of [unions types](unions.md) will be explained in a later section, they are only briefly mentioned here if you need them.
+The declaration and use of [union types](unions) will be explained in a later section, they are only briefly mentioned here if you need them.

package/doc/{migration.md → pages/migration.md}

@@ -1,6 +1,4 @@
-# Migration guide
-
-## Koffi 1.x to 2.x
+# Koffi 1.x to 2.x
 
 The API was changed in 2.x in a few ways, in order to reduce some excessively "magic" behavior and reduce the syntax differences between C and the C-like prototypes.
 
@@ -10,7 +8,7 @@ You may need to change your code if you use:
 - Opaque types
 - `koffi.introspect()`
 
-### Callback type changes
+## Callback type changes
 
 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.
 
@@ -61,13 +59,12 @@ let ret = TransferToJS('Niels', 27, (str, age) => {
 console.log(ret);
 ```
 
-Koffi 1.x only supported [transient callbacks](callbacks.md#javascript-callbacks), you must use Koffi 2.x for registered callbacks.
+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.
-```
+> [!NOTE]
+> The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
 
-### Opaque type changes
+## Opaque type changes
 
 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.
 
@@ -145,7 +142,7 @@ db = ptr[0];
 sqlite3_close_v2(db);
 ```
 
-### New koffi.introspect()
+## New koffi.introspect()
 
 In Koffi 1.x, `koffi.introspect()` would only work with struct types, and return the object passed to `koffi.struct()` to initialize the type. Now this function works with all types.
 

package/doc/{misc.md → pages/misc.md}

@@ -1,20 +1,17 @@
-# Miscellaneous
+# Types
 
-## Types
-
-### Introspection
+## Introspection
 
 *New in Koffi 2.0: `koffi.resolve()`, new in Koffi 2.2: `koffi.offsetof()`*
 
-```{note}
-The value returned by `introspect()` has **changed in version 2.0 and in version 2.2**.
-
-In Koffi 1.x, it could only be used with struct types and returned the object passed to koffi.struct() with the member names and types.
-
-Starting in Koffi 2.2, each record member is exposed as an object containing the name, the type and the offset within the record.
-
-Consult the [migration guide](migration.md) for more information.
-```
+> [!NOTE]
+> The value returned by `introspect()` has **changed in version 2.0 and in version 2.2**.
+>
+> In Koffi 1.x, it could only be used with struct types and returned the object passed to koffi.struct() with the member names and types.
+>
+> Starting in Koffi 2.2, each record member is exposed as an object containing the name, the type and the offset within the record.
+>
+> Consult the [migration guide](migration) for more information.
 
 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).
 
@@ -56,15 +53,50 @@ console.log(koffi.sizeof('long'));
 console.log(koffi.sizeof(koffi.types.long));
 ```
 
-### Aliases
+## Aliases
 
 *New in Koffi 2.0*
 
 You can alias a type with `koffi.alias(name, type)`. Aliased types are completely equivalent.
 
-## Settings
+## 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'
+});
 
-### Memory usage
+// 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
 
 For synchronous/normal calls, Koffi uses two preallocated memory blocks:
 
@@ -84,7 +116,7 @@ The same is true for asynchronous calls. When an asynchronous call is made, Koff
 
 There cannot be more than `max_async_calls` running at the same time.
 
-### Default settings
+## Default settings
 
 Setting              | Default | Description
 -------------------- | ------- | -----------------------------------------------
@@ -96,13 +128,13 @@ resident_async_pools | 2       | Number of resident pools for asynchronous calls
 max_async_calls      | 64      | Maximum number of ongoing asynchronous calls
 max_type_size        | 64 MiB  | Maximum size of Koffi types (for arrays and structs)
 
-## Usage statistics
+# Usage statistics
 
 *New in Koffi 2.3.2*
 
 You can use `koffi.stats()` to get a few statistics related to Koffi.
 
-## POSIX error codes
+# POSIX error codes
 
 *New in Koffi 2.3.14*
 
@@ -126,7 +158,7 @@ assert.equal(koffi.errno(), koffi.os.errno.EBADF);
 console.log('close() with invalid FD is POSIX compliant!');
 ```
 
-## Reset internal state
+# Reset internal state
 
 *New in Koffi 2.5.19*
 
@@ -137,6 +169,5 @@ You can use `koffi.reset()` to clear some Koffi internal state such as:
 
 This function is mainly intended for test code, when you execute the same code over and over and you need to reuse type names.
 
-```{warning}
-Trying to use a function or a type that was initially defined before the reset is undefined behavior and will likely lead to a crash!
-```
+> [!WARNING]
+> Trying to use a function or a type that was initially defined before the reset is undefined behavior and will likely lead to a crash!

package/doc/{output.md → pages/output.md}

@@ -1,12 +1,10 @@
-# Output parameters
-
-## Output and input/output
+# Output and input/output
 
 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.md#struct-types) (to/from JS objects)
-- [Unions](unions.md)
-- [Opaque types](input.md#opaque-types)
+- [Structs](input#struct-types) (to/from JS objects)
+- [Unions](unions)
+- [Opaque types](input#opaque-types)
 - String buffers
 
 In order to change an argument from input-only to output or input/output, use the following functions:
@@ -19,7 +17,7 @@ The same can be done when declaring a function with a C-like prototype string, w
 - `_Out_` for output parameters
 - `_Inout_` for dual input/output parameters
 
-### Primitive value
+## Primitive value
 
 This Windows example enumerate all Chrome windows along with their PID and their title. The `GetWindowThreadProcessId()` function illustrates how to get a primitive value from an output argument.
 
@@ -75,7 +73,7 @@ for (let hwnd = null;;) {
 }
 ```
 
-### Struct example
+## Struct example
 
 This example calls the POSIX function `gettimeofday()`, and uses the prototype-like syntax.
 
@@ -103,7 +101,7 @@ gettimeofday(tv, null);
 console.log(tv);
 ```
 
-### Opaque type example
+## Opaque type example
 
 This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.
 
@@ -130,7 +128,7 @@ let db = out[0];
 sqlite3_close_v2(db);
 ```
 
-### String buffer example
+## String buffer example
 
 *New in Koffi 2.2*
 
@@ -168,17 +166,16 @@ ConcatToBuffer(str1, str2, out);
 console.log(out[0]);
 ```
 
-## Output buffers
+# Output buffers
 
 In most cases, you can use buffers and typed arrays to provide output buffers. This works as long as the buffer only gets used while the native C function is being called. See [transient pointers](#transient-pointers) below for an example.
 
-```{warning}
-It is unsafe to keep the pointer around in the native code, or to change the contents outside of the function call where it is provided.
-
-If you need to provide a pointer that will be kept around, allocate memory with [koffi.alloc()](#stable-pointers) instead.
-```
+> [!WARNING]
+> It is unsafe to keep the pointer around in the native code, or to change the contents outside of the function call where it is provided.
+>
+> If you need to provide a pointer that will be kept around, allocate memory with [koffi.alloc()](#stable-pointers) instead.
 
-### Transient pointers
+## Transient pointers
 
 *New in Koffi 2.3*
 
@@ -220,9 +217,9 @@ console.log(vec1); // { x: 3, y: 2, z: 1 }
 console.log(vec2); // { x: 1, y: 2, z: 3 }
 ```
 
-See [decoding variables](variables.md#decode-to-js-values) for more information about the decode function.
+See [decoding variables](variables#decode-to-js-values) for more information about the decode function.
 
-### Stable pointers
+## Stable pointers
 
 *New in Koffi 2.8*
 
@@ -230,7 +227,7 @@ In some cases, the native code may need to change the output buffer at a later t
 
 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.md#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()](variables#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.