koffi 2.5.21-beta.3 → 2.6.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Version history
 
+### Koffi 2.6
+
+#### Koffi 2.6.0 (2023-09-13)
+
+**New features:**
+
+- Use [koffi.symbol()](variables.md#variable-definitions) to make pointers to exported variables (or other symbols)
+- Use [koffi.encode()](variables.md#encode-to-c-memory) to explictly encode data from JS to C memory
+- Use shared library [lazy-loading](functions.md#loading-options) (RTLD_LAZY) on POSIX platforms
+
+**Other changes:**
+
+- Print more helpful error for Win32/Win64 DLL mismatches
+- Add missing 'Union' primitive value in TS definition file
+
 ### Koffi 2.5
 
 #### Koffi 2.5.20 (2023-08-31)

package/doc/callbacks.md

@@ -153,14 +153,9 @@ let cb2 = koffi.register(store, store.get, 'IntCallback *'); // However in this
 
 Koffi does not have enough information to convert callback pointer arguments to an appropriate JS value. In this case, your JS function will receive an opaque *External* object.
 
-You can pass this value through to another C function that expects a pointer of the same type, or you can use `koffi.decode()` to decode it into something you can use in Javascript.
+You can pass this value through to another C function that expects a pointer of the same type, or you can use [koffi.decode()](variables.md#decode-to-js-values) function to decode pointer arguments.
 
-Some arguments are optional and this function can be called in several ways:
-
-- `koffi.decode(value, type)`: no offset, expect NUL-terminated strings
-- `koffi.decode(value, offset, type)`: explicit offset to add to the pointer before decoding
-
-The following example sorts an array of strings (in-place) with `qsort()`:
+The following examples uses it to sort an array of strings in-place with the standard C function `qsort()`:
 
 ```js
 // ES6 syntax: import koffi from 'koffi';
@@ -183,15 +178,6 @@ qsort(koffi.as(array, 'char **'), array.length, koffi.sizeof('void *'), (ptr1, p
 console.log(array); // Prints ['123', 'bar', 'foo', 'foobar']
 ```
 
-There is also an optional ending `length` argument that you can use in two cases:
-
-- Use it to give the number of bytes to decode in non-NUL terminated strings: `koffi.decode(value, 'char *', 5)`
-- Decode consecutive values into an array. For example, here is how you can decode an array with 3 float values: `koffi.decode(value, 'float', 3)`. This is equivalent to `koffi.decode(value, koffi.array('float', 3))`.
-
-```{note}
-In Koffi 2.2 and earlier versions, the length argument is only used to decode strings and is ignored otherwise.
-```
-
 ### Asynchronous callbacks
 
 *New in Koffi 2.2.2*

package/doc/functions.md

@@ -19,6 +19,22 @@ Starting with *Koffi 2.3.20*, you can explicitly unload a library by calling `li
 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*
+
+The `load` function can take an optional object argument, with the following options:
+
+```js
+const options = {
+    lazy: true // Use RTLD_LAZY (lazy-binding) on POSIX platforms (by default, use RTLD_NOW)
+};
+
+const lib = koffi.load('/path/to/shared/library.so', options);
+```
+
+More options may be added if needed.
+
 ## Function definitions
 
 ### Definition syntax

package/doc/index.rst

@@ -31,6 +31,7 @@ Table of contents
    output
    polymorphism
    unions
+   variables
    callbacks
    misc
    packaging

package/doc/polymorphism.md

@@ -105,4 +105,4 @@ console.log(vec1); // { x: 3, y: 2, z: 1 }
 console.log(vec2); // { x: 1, y: 2, z: 3 }
 ```
 
-See [pointer arguments](callbacks.md#decoding-pointer-arguments) for another example with the decode function.
+See [decoding variables](variables.md#decode-to-js-values) for more information about the decode function.

package/doc/variables.md

@@ -0,0 +1,100 @@
+# Exported variables
+
+## Variable definitions
+
+*New in Koffi 2.6*
+
+To find an exported and  declare a variable, use `lib.symbol(name, type)`. You need to specify its name and its type.
+
+```c
+int my_int = 42;
+const char *my_string = NULL;
+```
+
+```js
+const my_int = lib.symbol('my_int', 'int');
+const my_string = lib.symbol('my_string', 'const char *');
+```
+
+You cannot directly manipulate these variables, use:
+
+- [koffi.decode()](#decode-to-js-values) to read their value
+- [koffi.encode()](#encode-to-c-memory) to change their valuèe
+
+## Decode to JS values
+
+*New in Koffi 2.2, changed in Koffi 2.3*
+
+Use `koffi.decode()` to decode C pointers, wrapped as external objects or as simple numbers.
+
+Some arguments are optional and this function can be called in several ways:
+
+- `koffi.decode(value, type)`: no offset
+- `koffi.decode(value, offset, type)`: explicit offset to add to the pointer before decoding
+
+By default, Koffi expects NUL terminated strings when decoding them. See below if you need to specify the string length.
+
+The following example illustrates how to decode an integer and a C string variable.
+
+```c
+int my_int = 42;
+const char *my_string = "foobar";
+```
+
+```js
+const my_int = lib.symbol('my_int', 'int');
+const my_string = lib.symbol('my_string', 'const char *');
+
+console.log(koffi.decode(my_int, 'int')) // Prints 42
+console.log(koffi.decode(my_string, 'const char *')) // Prints "foobar"
+```
+
+There is also an optional ending `length` argument that you can use in two cases:
+
+- Use it to give the number of bytes to decode in non-NUL terminated strings: `koffi.decode(value, 'char *', 5)`
+- Decode consecutive values into an array. For example, here is how you can decode an array with 3 float values: `koffi.decode(value, 'float', 3)`. This is equivalent to `koffi.decode(value, koffi.array('float', 3))`.
+
+Thge example below will decode the symbol `my_string` defined above but only the first three bytes.
+
+```js
+// Only decode 3 bytes from the C string my_string
+console.log(koffi.decode(my_string, 'const char *', 3)) // Prints "foo"
+```
+
+```{note}
+In Koffi 2.2 and earlier versions, the length argument is only used to decode strings and is ignored otherwise.
+```
+
+## Encode to C memory
+
+*New in Koffi 2.6*
+
+Use `koffi.encode()` to encode C pointers, wrapped as external objects or as simple numbers.
+
+Some arguments are optional and this function can be called in several ways:
+
+- `koffi.encode(ref, type, value)`: no offset
+- `koffi.encode(ref, offset, type, value)`: explicit offset to add to the pointer before encoding
+
+We'll reuse the examples shown above and change the variable values with `koffi.encode()`.
+
+```c
+int my_int = 42;
+const char *my_string = NULL;
+```
+
+```js
+const my_int = lib.symbol('my_int', 'int');
+const my_string = lib.symbol('my_string', 'const char *');
+
+console.log(koffi.decode(my_int, 'int')) // Prints 42
+console.log(koffi.decode(my_string, 'const char *')) // Prints null
+
+koffi.encode(my_int, 'int', -1);
+koffi.encode(my_string, 'const char *', 'Hello World!');
+
+console.log(koffi.decode(my_int, 'int')) // Prints -1
+console.log(koffi.decode(my_string, 'const char *')) // Prints "Hello World!"
+```
+
+When encoding strings (either directly or embedded in arrays or structs), the memory will be bound to the raw pointer value and managed by Koffi. You can assign to the same string again and again with any leak or risk of use-after-free.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.5.21-beta.3",
-    "stable": "2.5.20",
+    "version": "2.6.0",
+    "stable": "2.6.0",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",

package/src/index.js

@@ -378,8 +378,8 @@ var require_package = __commonJS({
   "build/dist/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.5.21-beta.3",
-      stable: "2.5.20",
+      version: "2.6.0",
+      stable: "2.6.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",

package/src/koffi/src/ffi.cc

@@ -1644,6 +1644,18 @@ static Napi::Value LoadSharedLibrary(const Napi::CallbackInfo &info)
         ThrowError<Napi::TypeError>(env, "Unexpected %1 value for filename, expected string or null", GetValueType(instance, info[0]));
         return env.Null();
     }
+    if (info.Length() >= 2 && !IsObject(info[1])) {
+        ThrowError<Napi::TypeError>(env, "Unexpected %1 value for options, expected object", GetValueType(instance, info[1]));
+        return env.Null();
+    }
+
+#ifndef _WIN32
+    bool lazy = false;
+    if (info.Length() >= 2) {
+        Napi::Object options = info[1].As<Napi::Object>();
+        lazy = options.Get("lazy").ToBoolean();
+    }
+#endif
 
     if (!instance->memories.len) {
         AllocateMemory(instance, instance->config.sync_stack_size, instance->config.sync_heap_size);
@@ -1665,8 +1677,10 @@ static Napi::Value LoadSharedLibrary(const Napi::CallbackInfo &info)
     }
 #else
     if (info[0].IsString()) {
+        int flags = lazy ? RTLD_LAZY : RTLD_NOW;
+
         std::string filename = info[0].As<Napi::String>();
-        module = dlopen(filename.c_str(), RTLD_NOW);
+        module = dlopen(filename.c_str(), flags);
 
         if (!module) {
             const char *msg = dlerror();