原始内存访问辅助工具

🌐 Primitive memory access helpers

以下辅助工具可以在本地指针处读写原始值，也可以选择使用字节偏移：

🌐 The following helpers read and write primitive values at a native pointer, optionally with a byte offset:

  • ffi.getInt8(pointer[, offset])
  • ffi.getUint8(pointer[, offset])
  • ffi.getInt16(pointer[, offset])
  • ffi.getUint16(pointer[, offset])
  • ffi.getInt32(pointer[, offset])
  • ffi.getUint32(pointer[, offset])
  • ffi.getInt64(pointer[, offset])
  • ffi.getUint64(pointer[, offset])
  • ffi.getFloat32(pointer[, offset])
  • ffi.getFloat64(pointer[, offset])
  • ffi.setInt8(pointer, offset, value)
  • ffi.setUint8(pointer, offset, value)
  • ffi.setInt16(pointer, offset, value)
  • ffi.setUint16(pointer, offset, value)
  • ffi.setInt32(pointer, offset, value)
  • ffi.setUint32(pointer, offset, value)
  • ffi.setInt64(pointer, offset, value)
  • ffi.setUint64(pointer, offset, value)
  • ffi.setFloat32(pointer, offset, value)
  • ffi.setFloat64(pointer, offset, value)

这些助手执行直接的内存读写。pointer 必须是一个 bigint，指向有效的可读或可写的原生内存。提供 offset 时，会将其解释为从 pointer 开始的字节偏移。

🌐 These helpers perform direct memory reads and writes. pointer must be a bigint referring to valid readable or writable native memory. offset, when provided, is interpreted as a byte offset from pointer.

getter 辅助函数为 8 位、16 位和 32 位整数类型以及浮点类型返回 JavaScript number 值。它们为 64 位整数类型返回 bigint 值。

🌐 The getter helpers return JavaScript number values for 8-, 16-, and 32-bit integer types and for floating-point types. They return bigint values for 64-bit integer types.

设置器辅助函数需要一个明确的字节偏移量，并在将提供的 JavaScript 值写入内存之前验证其与目标原生类型的匹配。 对于 setInt64() 和 setUint64()，bigint 值可以直接接受； 数字输入必须是 JavaScript 安全整数范围内的整数。

🌐 The setter helpers require an explicit byte offset and validate the supplied JavaScript value against the target native type before writing it into memory. For setInt64() and setUint64(), bigint values are accepted directly; numeric inputs must be integers within JavaScript's safe integer range.

const {
  getInt32,
  setInt32,
} = require('node:ffi');

setInt32(ptr, 0, 42);
console.log(getInt32(ptr, 0));

像本模块中的其他原始内存辅助函数一样，这些 API 不跟踪所有权、边界或生命周期。传递无效指针、使用错误的偏移量或通过过期指针写入都可能破坏内存或导致进程崩溃。

🌐 Like the other raw memory helpers in this module, these APIs do not track ownership, bounds, or lifetime. Passing an invalid pointer, using the wrong offset, or writing through a stale pointer can corrupt memory or crash the process.