lib: add new methods and error codes

Signed-off-by: Paolo Insogna <paolo@cowtech.it>
PR-URL: #62762
Reviewed-By: Xuguang Mei <meixuguang@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Bryan English <bryan@bryanenglish.com>

Author: ShogunPanda

benchmark/ffi/getpid.js

@@ -0,0 +1,25 @@
+'use strict';
+
+constcommon=require('../common.js');
+constffi=require('node:ffi');
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+},{
+flags: ['--experimental-ffi'],
+});
+
+const{ lib, functions }=ffi.dlopen(null,{
+uv_os_getpid: {result: 'i32',parameters: []},
+});
+
+constgetpid=functions.uv_os_getpid;
+
+functionmain({ n }){
+bench.start();
+for(leti=0;i<n;++i)
+getpid();
+bench.end(n);
+
+lib.close();
+}

doc/api/errors.md

@@ -1332,6 +1332,24 @@ added: v14.0.0
 Used when a feature that is not available
 to the current platform which is running Node.js is used.
 
+<aid="ERR_FFI_CALL_FAILED"></a>
+
+### `ERR_FFI_CALL_FAILED`
+
+A low-level FFI call failed.
+
+<aid="ERR_FFI_INVALID_POINTER"></a>
+
+### `ERR_FFI_INVALID_POINTER`
+
+An invalid pointer was passed to an FFI operation.
+
+<aid="ERR_FFI_LIBRARY_CLOSED"></a>
+
+### `ERR_FFI_LIBRARY_CLOSED`
+
+An operation was attempted on an FFI dynamic library after it was closed.
+
 <aid="ERR_FS_CP_DIR_TO_NON_DIR"></a>
 
 ### `ERR_FS_CP_DIR_TO_NON_DIR`

doc/api/ffi.md

@@ -165,12 +165,15 @@ const path = `libsqlite3.${suffix}`;
 added: REPLACEME
 -->
 
-*`path` {string} Path to a dynamic library.
+*`path` {string|null} Path to a dynamic library, or `null` to resolve symbols
+ from the current process image.
 *`definitions` {Object} Symbol definitions to resolve immediately.
 * Returns: {Object}
 
 Loads a dynamic library and resolves the requested function definitions.
 
+On Windows passing `null` is not supported.
+
 When `definitions` is omitted, `functions` is returned as an empty object until
 symbols are resolved explicitly.
 
@@ -237,10 +240,13 @@ Represents a loaded dynamic library.
 
 ### `new DynamicLibrary(path)`
 
-*`path` {string} Path to a dynamic library.
+*`path` {string|null} Path to a dynamic library, or `null` to resolve symbols
+ from the current process image.
 
 Loads the dynamic library without resolving any functions eagerly.
 
+On Windows passing `null` is not supported.
+
 ```cjs
 const { DynamicLibrary } =require('node:ffi');
 
@@ -603,6 +609,55 @@ available storage. This function does not allocate memory on its own.
 
 `buffer` must be a Node.js `Buffer`.
 
+## `ffi.exportArrayBuffer(arrayBuffer, pointer, length)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`arrayBuffer` {ArrayBuffer}
+*`pointer` {bigint}
+*`length` {number}
+
+Copies bytes from an `ArrayBuffer` into native memory.
+
+`length` must be at least `arrayBuffer.byteLength`.
+
+`pointer` must refer to writable native memory with at least `length` bytes of
+available storage. This function does not allocate memory on its own.
+
+## `ffi.exportArrayBufferView(arrayBufferView, pointer, length)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`arrayBufferView` {ArrayBufferView}
+*`pointer` {bigint}
+*`length` {number}
+
+Copies bytes from an `ArrayBufferView` into native memory.
+
+`length` must be at least `arrayBufferView.byteLength`.
+
+`pointer` must refer to writable native memory with at least `length` bytes of
+available storage. This function does not allocate memory on its own.
+
+## `ffi.getRawPointer(source)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`source` {Buffer|ArrayBuffer|ArrayBufferView}
+* Returns: {bigint}
+
+Returns the raw memory address of JavaScript-managed byte storage.
+
+This is unsafe and dangerous. The returned pointer can become invalid if the
+underlying memory is detached, resized, transferred, or otherwise invalidated.
+Using stale pointers can cause memory corruption or process crashes.
+
 ## Safety notes
 
 The `node:ffi` module does not track pointer validity, memory ownership, or

lib/ffi.js

@@ -2,9 +2,13 @@
 
 const{
  ObjectFreeze,
+ ObjectPrototypeToString,
 }=primordials;
 const{ Buffer }=require('buffer');
 const{ emitExperimentalWarning }=require('internal/util');
+const{
+ isArrayBufferView,
+}=require('internal/util/types');
 const{
 codes: {
 ERR_ACCESS_DENIED,
@@ -32,6 +36,8 @@ const {
  getUint64,
  getFloat32,
  getFloat64,
+ exportBytes,
+ getRawPointer,
  setInt8,
  setUint8,
  setInt16,
@@ -114,21 +120,52 @@ function exportString(str, data, len, encoding = 'utf8') {
 targetBuffer.fill(0,dataLength,dataLength+terminatorSize);
 }
 
-functionexportBuffer(buffer,data,len){
+functionexportBuffer(source,data,len){
 checkFFIPermission();
 
-if(!Buffer.isBuffer(buffer)){
-thrownewERR_INVALID_ARG_TYPE('buffer','Buffer',buffer);
+if(!Buffer.isBuffer(source)){
+thrownewERR_INVALID_ARG_TYPE('buffer','Buffer',source);
 }
 
 validateInteger(len,'len',0);
 
-if(len<buffer.length){
-thrownewERR_OUT_OF_RANGE('len',`>= ${buffer.length}`,len);
+if(len<source.length){
+thrownewERR_OUT_OF_RANGE('len',`>= ${source.length}`,len);
 }
 
-consttargetBuffer=toBuffer(data,len,false);
-buffer.copy(targetBuffer,0,0,buffer.length);
+exportBytes(source,data,len);
+}
+
+functionexportArrayBuffer(source,data,len){
+checkFFIPermission();
+
+if(ObjectPrototypeToString(source)!=='[object ArrayBuffer]'){
+thrownewERR_INVALID_ARG_TYPE('arrayBuffer','ArrayBuffer',source);
+}
+
+validateInteger(len,'len',0);
+
+if(len<source.byteLength){
+thrownewERR_OUT_OF_RANGE('len',`>= ${source.byteLength}`,len);
+}
+
+exportBytes(source,data,len);
+}
+
+functionexportArrayBufferView(source,data,len){
+checkFFIPermission();
+
+if(!isArrayBufferView(source)){
+thrownewERR_INVALID_ARG_TYPE('arrayBufferView','ArrayBufferView',source);
+}
+
+validateInteger(len,'len',0);
+
+if(len<source.byteLength){
+thrownewERR_OUT_OF_RANGE('len',`>= ${source.byteLength}`,len);
+}
+
+exportBytes(source,data,len);
 }
 
 constsuffix=process.platform==='win32' ? 'dll' : process.platform==='darwin' ? 'dylib' : 'so';
@@ -163,6 +200,8 @@ module.exports = {
  dlopen,
  dlclose,
  dlsym,
+ exportArrayBuffer,
+ exportArrayBufferView,
  exportString,
  exportBuffer,
  getInt8,
@@ -175,6 +214,7 @@ module.exports = {
  getUint64,
  getFloat32,
  getFloat64,
+ getRawPointer,
  setInt8,
  setUint8,
  setInt16,