ffi.mem

Low-level memory operations: allocation, typed reads/writes, pointer chains, memory protection, pattern scanning, and heap inspection.

Functions

ffi.mem.alloc(size)

Allocates a block of memory of the given size using malloc and returns its address.

Parameters

Name	Type	Description
size	number	Number of bytes to allocate.

Returns

Type	Description
number	Address of the newly allocated block.

ffi.mem.free(address)

Frees a block of memory previously allocated by mem.alloc. Passing an invalid address or double-freeing is undefined behavior.

Parameters

Name	Type	Description
address	number	Address of the block to free.

ffi.mem.copy(dest, src, size)

Copies size bytes from src to dest using memcpy. The regions must not overlap.

Parameters

Name	Type	Description
dest	number	Destination address.
src	number	Source address.
size	number	Number of bytes to copy.

ffi.mem.fill(address, value, size)

Fills size bytes starting at address with the given byte value using memset.

Parameters

Name	Type	Description
address	number	Starting address.
value	number	Byte value to fill with (only the low 8 bits are used).
size	number	Number of bytes to fill.

ffi.mem.copy_from_string(dest, str)

Copies the raw bytes of a Lua string (including embedded null bytes) to the given address. The number of bytes copied equals the string's length.

Parameters

Name	Type	Description
dest	number	Destination address.
str	string	Source data as a (possibly binary) Lua string.

ffi.mem.read_u8(address)

Reads an unsigned 8-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	Value in the range [0, 255].

ffi.mem.read_i8(address)

Reads a signed 8-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	Value in the range [-128, 127].

ffi.mem.read_u16(address)

Reads an unsigned 16-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	Value in the range [0, 65535].

ffi.mem.read_i16(address)

Reads a signed 16-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	Value in the range [-32768, 32767].

ffi.mem.read_u32(address)

Reads an unsigned 32-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	Value in the range [0, 4294967295].

ffi.mem.read_i32(address)

Reads a signed 32-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	Value in the range [-2147483648, 2147483647].

ffi.mem.read_u64(address)

Note: Large 64-bit values may lose precision when stored as a Lua `number` (double). Values up to 2^53 are exact.

Reads an unsigned 64-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	The 64-bit unsigned value as a double.

ffi.mem.read_i64(address)

Note: Large 64-bit values may lose precision when stored as a Lua `number` (double). Values in `[-2^53, 2^53]` are exact.

Reads a signed 64-bit integer from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	The 64-bit signed value as a double.

ffi.mem.read_f32(address)

Reads a 32-bit IEEE 754 float from the given address and returns it widened to a double.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	The float value.

ffi.mem.read_f64(address)

Reads a 64-bit IEEE 754 double from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	The double value.

ffi.mem.read_ptr(address)

Reads a 64-bit pointer-sized value from the given address.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number	The pointer value as a double.

ffi.mem.read_string(address, max_len?)

Reads a null-terminated string from memory starting at address. If max_len is provided, at most that many characters are read (via strnlen).

Parameters

Name	Type	Description
address	number	Address of the first character.
max_len?	number	Maximum number of characters to scan for the null terminator.

Returns

Type	Description
string	The string read from memory.

ffi.mem.try_read_u8(address)

Protected version of read_u8. Returns the value on success, or nothing on access violation or other hardware exception. Does not throw a Lua error.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_i8(address)

Protected version of read_i8. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_u16(address)

Protected version of read_u16. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_i16(address)

Protected version of read_i16. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_u32(address)

Protected version of read_u32. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_i32(address)

Protected version of read_i32. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_u64(address)

Protected version of read_u64. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_i64(address)

Protected version of read_i64. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_f32(address)

Protected version of read_f32. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_f64(address)

Protected version of read_f64. Returns the value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The value, or nothing if the read faulted.

ffi.mem.try_read_ptr(address)

Protected version of read_ptr. Returns the pointer value on success, or nothing on fault.

Parameters

Name	Type	Description
address	number	Memory address to read from.

Returns

Type	Description
number?	The pointer value, or nothing if the read faulted.

ffi.mem.try_read_string(address, max_len?)

Note: Unlike the numeric `try_read_*` variants, this uses SEH internally because SSE2-vectorized `strnlen` cannot be safely unwound by the VEH longjmp path.

Protected version of read_string. Uses SEH to catch access violations during the strnlen call. If max_len is omitted the entire string is read with no length limit. Returns nothing on fault.

Parameters

Name	Type	Description
address	number	Address of the first character.
max_len?	number	Maximum number of characters to scan for the null terminator.

Returns

Type	Description
string?	The string read from memory, or nothing on fault.

ffi.mem.write_u8(address, value)

Writes an unsigned 8-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (truncated to 8 bits).

ffi.mem.write_i8(address, value)

Writes a signed 8-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (truncated to 8 bits).

ffi.mem.write_u16(address, value)

Writes an unsigned 16-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (truncated to 16 bits).

ffi.mem.write_i16(address, value)

Writes a signed 16-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (truncated to 16 bits).

ffi.mem.write_u32(address, value)

Writes an unsigned 32-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (truncated to 32 bits).

ffi.mem.write_i32(address, value)

Writes a signed 32-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (truncated to 32 bits).

ffi.mem.write_u64(address, value)

Writes an unsigned 64-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (converted from double; precision limited to 53 bits).

ffi.mem.write_i64(address, value)

Writes a signed 64-bit integer to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write (converted from double; precision limited to 53 bits).

ffi.mem.write_f32(address, value)

Writes a 32-bit float to the given address (narrows the double value).

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

ffi.mem.write_f64(address, value)

Writes a 64-bit double to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

ffi.mem.write_ptr(address, value)

Writes a 64-bit pointer-sized value to the given address.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Pointer value to write.

ffi.mem.write_string(address, str)

Copies a Lua string (plus its null terminator) into memory at the given address. The number of bytes written is #str + 1.

Parameters

Name	Type	Description
address	number	Destination address.
str	string	String to write.

ffi.mem.try_write_u8(address, value)

Protected version of write_u8. Returns true on success, false if an access violation or hardware exception occurred.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_i8(address, value)

Protected version of write_i8. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_u16(address, value)

Protected version of write_u16. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_i16(address, value)

Protected version of write_i16. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_u32(address, value)

Protected version of write_u32. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_i32(address, value)

Protected version of write_i32. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_u64(address, value)

Protected version of write_u64. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_i64(address, value)

Protected version of write_i64. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_f32(address, value)

Protected version of write_f32. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_f64(address, value)

Protected version of write_f64. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_ptr(address, value)

Protected version of write_ptr. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Memory address to write to.
value	number	Value to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.try_write_string(address, str)

Protected version of write_string. Copies the string and its null terminator into memory. Returns true on success, false on fault.

Parameters

Name	Type	Description
address	number	Destination address.
str	string	String to write.

Returns

Type	Description
boolean	true if the write succeeded, false on fault.

ffi.mem.sizeof(type)

Returns the byte size of a named primitive type. Recognized type names are u8, i8, u16, i16, u32, i32, f32, u64, i64, f64, and ptr. Returns 0 for unrecognized type names.

Parameters

Name	Type	Description
type	string	Type name string, e.g. "u32" or "ptr".

Returns

Type	Description
number	Size in bytes (1, 2, 4, or 8), or 0 for an unrecognized type.

ffi.mem.unwrap_userdata(userdata)

Extracts the raw pointer address from a light userdata value and returns it as a number.

Parameters

Name	Type	Description
userdata	any	A light userdata value.

Returns

Type	Description
number	The underlying pointer address.

ffi.mem.protect(address, size, rights)

Note: The rights string is parsed character-by-character (case-insensitive). Any combination of `r`, `w`, `x` maps to the corresponding `PAGE_*` constant. An empty or unrecognized string maps to `PAGE_NOACCESS`.

Changes the memory protection of a region using VirtualProtect. The rights string is a combination of the letters r (read), w (write), and x (execute); e.g. "rwx", "rx", "r". Returns true on success, false on failure.

Parameters

Name	Type	Description
address	number	Base address of the region.
size	number	Size of the region in bytes.
rights	string	Protection string, e.g. "rwx", "rx", "r".

Returns

Type	Description
boolean	true if VirtualProtect succeeded, false otherwise.

ffi.mem.query(address)

Note: Protection strings use the same format as `mem.protect` plus modifier suffixes: `+g` (guard), `+n` (no-cache), `+w` (write-combine). The `state` field is `"commit"`, `"reserve"`, or `"free"`. The `type` field is `"image"`, `"mapped"`, or `"private"`.

Queries virtual memory information for the page containing address via VirtualQuery. Returns a table of region attributes, or nothing if the query fails.

Parameters

Name	Type	Description
address	number	Any address within the memory region to query.

Returns

Type	Description
table?	A table with fields: base (number), alloc_base (number), size (number), state (string), protect (string), alloc_protect (string), type (string). Returns nothing if VirtualQuery fails.

ffi.mem.deref(base, offsets)

Note: The offsets table is a sequential array. Negative offsets are allowed. After the last offset is applied the result is returned as an address without dereferencing.

Follows a multi-level pointer chain starting from base. For each offset in the table, the offset is added to the current address and (for all but the last offset) the result is dereferenced as a 64-bit pointer. Returns the final computed address, or nothing if any intermediate pointer is null or causes an access violation.

Parameters

Name	Type	Description
base	number	Starting address.
offsets	table	Ordered array of integer offsets to apply.

Returns

Type	Description
number?	The resolved address, or nothing if the chain is broken.

ffi.mem.heaps()

Enumerates all committed heap regions in the current process. Returns a table of {base, size} entries, one per heap region.

Returns

Type	Description
table	Array of tables, each with base (number, region start address) and size (number, committed bytes).

ffi.mem.scan(base, size, pattern, no_mask?)

Scans a memory region for a byte pattern. The pattern is an IDA-style hex string where each byte is a two-digit hex value and ?? denotes a wildcard byte, e.g. "48 89 5C ?? ?? 48 8B".

When no_mask is false (the default), the pattern is first parsed for explicit ?? wildcards. If no wildcards are present, an auto-masking heuristic is applied to detect relative offsets and other position-dependent bytes, replacing them with ?? automatically and printing the masked form to the console.

Returns the address of the first match, or nothing if not found.

Parameters

Name	Type	Description
base	number	Start of the region to scan.
size	number	Length of the region in bytes.
pattern	string	IDA-style hex pattern, e.g. "48 89 5C ?? ?? 48 8B".
no_mask?	boolean	If true, disables auto-masking and treats the pattern as a literal byte string (no wildcard substitution). Defaults to false.

Returns

Type	Description
number?	Address of the first match, or nothing if not found.

ffi.mem.memory_scan(pattern, no_mask?, min_size?)

Note: The scan excludes the internal buffer holding the parsed pattern bytes to avoid false positives.

Scans all committed readable pages in the entire process for a byte pattern. Uses the same pattern format and auto-masking logic as mem.scan.

Adjacent pages with the same protection flags are coalesced into a single scan region. Regions smaller than min_size bytes are skipped.

Returns a table containing the address of every match found.

Parameters

Name	Type	Description
pattern	string	IDA-style hex pattern, e.g. "48 89 5C ?? ?? 48 8B".
no_mask?	boolean	If true, disables auto-masking. Defaults to false.
min_size?	number	Minimum region size in bytes to include in the scan. Defaults to 0x10000 (65536).

Returns

Type	Description
table	Array of addresses (numbers) where the pattern was found. Empty if no matches.

ffi.mem.addr_to_pat(address)

Converts a 64-bit address to an IDA-style little-endian byte pattern string. Useful for building patterns that contain an absolute address.

Parameters

Name	Type	Description
address	number	The address to convert.

Returns

Type	Description
string	An 8-byte little-endian hex pattern, e.g. "78 56 34 12 00 00 00 00".

ffi.mem.to_binary_string(address, size)

Copies size bytes from address and returns them as a binary Lua string. Useful for taking memory snapshots or passing raw data to other APIs.

Parameters

Name	Type	Description
address	number	Start of the memory region.
size	number	Number of bytes to copy.

Returns

Type	Description
string	A binary string containing the raw bytes.

ffi.mem.function_to_ptr(func)

Returns the native code pointer of a C function. If the function is not a C function, returns nil.

Parameters

Name	Type	Description
func	function	A Lua C function.

Returns

Type	Description
number?	The native code address, or nil if the function is not a C function.

ffi.mem.upvalue(func, index)

Retrieves an upvalue from a function by index, bypassing any sandbox restrictions on debug.getupvalue. Returns the upvalue's value and its name.

Parameters

Name	Type	Description
func	function	The function whose upvalue to retrieve.
index	number	1-based upvalue index.

Returns

Type	Description
any?	The upvalue's value, or nothing if the index is out of range.
string?	The upvalue's name, or nothing if the index is out of range.