Module lua-ctables-extra

Additional extra API (optional, true)

Extends lua-ctables with more features but which are not necessary for core usage.

This is a sub-module incorporated in the parent lua-ctable (if built)

See also:

Info:

  • Copyright: © Michael Ambrus 2024
  • License: MIT
  • Author: Michael Ambrus michael@ambrus.se

Functions

balloc (Dimensions, Sz, Initializer) Allocate C-chunk of memory (binary blob)

C-array/-buffer for test or SHB-emulation

Allocates a chuck of memory in C-space, optionally initialize it with patterns.
bfree (Address) Free C-chunk of memory (binary blob)

Call C-lib free() on Address to pair-up with balloc() or potentially any other valid C-pointer to allocated memory that you can determine.
braw (Address, Size, Groupsize) Binary dump a C-buffer to stderr in hex
i2u (Address) Cast a Lua-integer/number to a LUA_TLIGHTUSERDATA

Use as wrapper for cases there an userdata ptr (void *) address is (some-how) known by it's numerical value only.
n2u (Address, isinteger, issigned, size) Write number to LUA_TLIGHTUSERDATA
u2n (Address, isinteger, issigned, size) Read number from LUA_TLIGHTUSERDATA


Functions

balloc (Dimensions, Sz, Initializer)
Allocate C-chunk of memory (binary blob)

C-array/-buffer for test or SHB-emulation

Allocates a chuck of memory in C-space, optionally initialize it with patterns. Order does not matter but good to use as convention the same order as where it matters in this module (memory layout order - {...,z,y,x)). I.e. "innermost" last.

Size is given as a table of dimensions and size of each element to match other API's in this module.

Parameters:

  • Dimensions table 1D Table with dimensions. Order does not matter but good to use as convention as where it matters in this module. I.e. "innermost" first which is the same as memory-layout i.e. {...,z,y,x)
  • Sz number Size of each element
  • Initializer table (optional). If not given, chunk is initialized with zeros.

Returns:

  1. userdata Address of the blob (void *), or nil on failure
  2. integer Size in bytes, or errno on failure (see malloc)
  3. string On fail: A descriptive text for errno

See also:

Usage:

    blob, sz = ctables.balloc({34,60}, 4, {0x0101, 0xF0F00000,0x30308080})
print(blob, sz)
--> userdata: 0x557ef7567270        8160
bfree (Address)
Free C-chunk of memory (binary blob)

Call C-lib free() on Address to pair-up with balloc() or potentially any other valid C-pointer to allocated memory that you can determine. Note* that this function is as crude as libc's free(). I.e.

  • Pointer must be valid from libc's perspective. This includes NULL however
  • Doesn't protect against double-free
  • It returns nothing

Failing to comply with the above will (best case) crash not only your application but also the Lua VM. "Best-case" because you'd at least know you're crap at coding. "Worst-case" is not knowing, i.e. code continues executing and fails in a much nastier way far away from the cause.

Parameters:

  • Address userdata C-pointer to the blob (void *)

See also:

Usage:

    blob = ctables.balloc({34,60}, 4)
print(blob)                                     --> userdata: 0x557ef7569ba0
type(blob)                                      --> userdata

ctables.bfree(blob)
-- Note: blob is now invalid. Lua can not know as it treats it as number
type(blob)                                      --> userdata

-- ANY consecutive operation on this value is invalid. Another call to bfree
-- for example is a double-free.
braw (Address, Size, Groupsize)
Binary dump a C-buffer to stderr in hex

Parameters:

  • Address userdata C-pointer to the blob (void *)
  • Size integer of buffer. Note: in bytes
  • Groupsize integer bytes (1, 2, 4, 8). Optional, default 4

Usage:

    > blob, sz = ctables.balloc({8, 5}, 4, {0x1100, 0x0F0F})
> ctables.braw(blob, sz, 4)
0000: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
001c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
003c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
005c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
007c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
>
> ctables.free(blob)
>
i2u (Address)
Cast a Lua-integer/number to a LUA_TLIGHTUSERDATA

Use as wrapper for cases there an userdata ptr (void *) address is (some-how) known by it's numerical value only.

This wrapper is useful for (slightly) more transparent Lua-code. Note that Lua integer limitations still apply as value has to fit top-op stack as a numerical type able to carry a pointe to reach the inside of the cast without any truncation loss.

Parameters:

  • Address number of a C-pointer (void *) as integer or number

Returns:

    userdata Converted address into a valid LUA_TLIGHTUSERDATA

Usage:

    ctables.i2u(0x12345)                                --> userdata: 0x12345
-- A Highly hypothetical use as floats are never addresses
ctables.i2u(10.0)                                   --> userdata: 0xa

-- A slightly more "realistic" case simulating a getting an address from an
-- "unknown" source as a numerical value (a Lua-number of some kind)

blob, sz = ctables.balloc({8, 5}, 4, {0x1100, 0x0F0F})
nblob = tonumber( string.sub( tostring(blob),11) )        -- Simulate magic ptr addr
print(type(blob) .. " " .. type(nblob))                   -- Verify "wrong type"
--> userdata number

ctables.braw( ctables.i2u(nblob), sz, 4)
--> 0000: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
--> 001c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
--> 003c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
--> 005c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f
--> 007c: 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f 00001100 00000f0f

ctables.free(blob)
n2u (Address, isinteger, issigned, size)
Write number to LUATLIGHTUSERDATA To LUATLIGHTUSERDATA as defined by arguments 3-5, write userdata

Parameters:

  • Address userdata of a C-pointer (void *)
  • isinteger boolean
  • issigned boolean
  • size integer

Returns:

  1. Number Value
  2. boolean Success

Usage:

    blob, sz = ctables.balloc({1}, 4)
-- At userdatata "blob", write int32_t then read it back
ctables.n2u(blob, 0x11)                             --> true
ctables.u2n(blob)                                   --> 17.0

ctables.braw( blob, sz, 4)
-- 0000: 00000011

-- At userdatata "blob", write/read (signed) int16_t
ctables.n2u(blob, 0x8010, true, true, 2)            --> true
ctables.braw( blob, sz, 2)
-- 0000: 8010 0000

ctables.u2n(blob, true, true, 2)                    --> -32752.0
u2n (Address, isinteger, issigned, size)
Read number from LUATLIGHTUSERDATA From LUATLIGHTUSERDATA as defined by arguments 2-4, get userdata as number

Parameters:

  • Address userdata of a C-pointer (void *)
  • isinteger boolean
  • issigned boolean
  • size integer

Returns:

    Number Value

See also:

generated by LDoc 1.5.0 Last updated 2024-09-16 20:16:45