dataModule

Direct memory access and manipulation.

Class data

data:__len ()
data:__tostring ()
data:checksum ([offset=0[, length]])	Returns the Internet checksum of the `length` bytes at `offset`.
data:getbyte (offset)	Reads an unsigned 8-bit integer at `offset`; an alias of getuint8.
data:getint16 (offset)	Reads a signed 16-bit integer at `offset`.
data:getint32 (offset)	Reads a signed 32-bit integer at `offset`.
data:getint64 (offset)	Reads a signed 64-bit integer at `offset`.
data:getint8 (offset)	Reads a signed 8-bit integer at `offset`.
data:getstring (offset[, length])	Reads `length` bytes at `offset` as a string.
data:getuint16 (offset)	Reads an unsigned 16-bit integer at `offset`.
data:getuint32 (offset)	Reads an unsigned 32-bit integer at `offset`.
data:getuint8 (offset)	Reads an unsigned 8-bit integer at `offset`.
data:resize (new_size)	Resizes the buffer; the bytes it keeps survive and the bytes a growth adds read as zeros.
data:setbyte (offset, value)	Writes an 8-bit integer at `offset`; an alias of setuint8.
data:setint16 (offset, value)	Writes a signed 16-bit integer at `offset`.
data:setint32 (offset, value)	Writes a signed 32-bit integer at `offset`.
data:setint64 (offset, value)	Writes a signed 64-bit integer at `offset`.
data:setint8 (offset, value)	Writes a signed 8-bit integer at `offset`.
data:setstring (offset, s)	Writes the bytes of `s` at `offset`.
data:setuint16 (offset, value)	Writes an unsigned 16-bit integer at `offset`.
data:setuint32 (offset, value)	Writes an unsigned 32-bit integer at `offset`.
data:setuint8 (offset, value)	Writes an unsigned 8-bit integer at `offset`.

data

load (path, maxbytes)	Reads a file whole into a new buffer, which it owns.
new (size[, mode])	Allocates a buffer of `size` bytes, zeroed.

Class data in detail

Represents a byte buffer. This is a userdata object returned by data.new(), by data.load() and by the modules that expose kernel memory (as skb:data()), read and written through the getuint/setuint accessors below.

Offsets start at 0, and the integer accessors use host byte order: convert a network field with byteorder, as byteorder.ntoh16(d:getuint16(12)). A data object a binding hands to a callback, or skb:data() returns for that callback’s skb, views kernel memory only while that callback runs: afterwards its length is 0 and every access raises “out of bounds”, so copy what you keep with getstring. skb:copy():data() views the copy’s own buffer until the copy is collected, and is then cleared the same way. A write to a view a binding marks read only raises “read only”.

A binding that builds over the bytes of a buffer, as set.fromdata does, takes only one that owns its memory, from data.new() or data.load(), and makes it read only for good: its setters and resize raise “read only” from then on, while #, the getters, getstring, checksum and tostring keep reading.

An integer setter takes a value of its width read either signed or unsigned, so setint8 and setuint8 both store -1 and 255 as the same byte, and raises “out of bounds” for a value past it.

data:__len ()

Returns

integer

data:__tostring ()

Returns

string

data:checksum ([offset=0[, length]])

Returns the Internet checksum of the length bytes at offset. It is their 16-bit ones'-complement sum, folded and complemented as csum_fold does, so a region that holds its correct checksum gives 0.

Parameters

offset integer (default 0)
length integer number of bytes; default: from offset to end (optional)

Returns

integer

Raises

if out of bounds

data:getbyte (offset)

Reads an unsigned 8-bit integer at offset; an alias of getuint8.

Parameters

offset integer

Returns

integer

Raises

if out of bounds

data:getint16 (offset)

Reads a signed 16-bit integer at offset.

Parameters

offset integer

Returns

integer

Raises

if out of bounds

data:getint32 (offset)

Reads a signed 32-bit integer at offset.

Parameters

offset integer

Returns

integer

Raises

if out of bounds

data:getint64 (offset)

Reads a signed 64-bit integer at offset.

Parameters

offset integer

Returns

integer

Raises

if out of bounds

data:getint8 (offset)

Reads a signed 8-bit integer at offset.

Parameters

offset integer

Returns

integer

Raises

if out of bounds

data:getstring (offset[, length])

Reads length bytes at offset as a string.

Parameters

offset integer
length integer number of bytes; default: from offset to end (optional)

Returns

string

Raises

“out of bounds” for an offset or a length that reaches past the size, or a negative one

data:getuint16 (offset)

Reads an unsigned 16-bit integer at offset.

Parameters

offset integer

Returns

integer

Raises

if out of bounds

data:getuint32 (offset)

Reads an unsigned 32-bit integer at offset.

Parameters

offset integer

Returns

integer

Raises

if out of bounds

data:getuint8 (offset)

Reads an unsigned 8-bit integer at offset.

Parameters

offset integer

Parameters

offset integer
value integer from -128 to 255

Raises

if out of bounds or read-only

data in detail

load (path, maxbytes)

Reads a file whole into a new buffer, which it owns. The read is the kernel’s own for the files it loads, so the file passes the security hooks those pass. The path is resolved by the calling task. Reading sleeps, so call it where it can sleep (a process-context runtime, or any runtime’s load).

Parameters

path string the file.
maxbytes integer the largest file it reads, in bytes, from 1 up to INT_MAX.

Returns

data

"shared"

Raises

“out of bounds” for a maxbytes outside that range; ENOENT, EACCES, EFBIG for a file larger than maxbytes, refused before it is read, EINVAL for an empty or non-regular file, ETXTBSY while the file is open for writing, ENOMEM when the buffer cannot be allocated, EIO for a file that reads shorter than its size, as a sysfs attribute does, or the errno a security module refuses the read with; or not allowed once the runtime is armed (its script body has returned) on an interrupt-context runtime

Usage

local db = data.load("/lib/firmware/regulatory.db", 64 << 10)

new (size[, mode])

Allocates a buffer of size bytes, zeroed.

Parameters

size integer number of bytes, from 1 up to INT_MAX.
mode string "shared" (default) or "single"; a "single" buffer cannot be passed to another runtime. (optional)

Returns

data

Raises

if out of bounds, the mode is invalid, or allocation fails