Lunatik
Lua API · Packets and eBPF

bpf.mapModule

High-level view over pinned eBPF maps.

Each constructor mirrors the one in bpf, taking the packing spec of what the map holds. Key-value maps become table proxies: indexing looks values up, assignment updates, assigning nil deletes, and pairs iterates. Keyless maps become objects, with push, pop and peek.

Keys and values are opaque fixed-size buffers to eBPF. A spec is either a string.pack format (e.g. "I4", "c6") or a struct codec, and says both how many bytes it takes, validated against the map on open, and how to read them. Specs that pack a single value take and return it as a scalar; multi-value formats and struct codecs take and return an array of values, in field order.

Operations on a table proxy come from outside it (close and info are module functions, as in Lua’s table library or rcu.foreach), so any key the spec can encode is a valid map key.

Conditional updates (BPF_NOEXIST/BPF_EXIST) and the boolean results belong to the raw API.

As in bpf, a softirq or hardirq runtime opens maps only while its script body runs; the proxies can then be used from handlers.

See also

Usage

local map = require("bpf.map")

local counters <close> = map.hash("/sys/fs/bpf/counters", "I4", "I4")
counters[1] = 42
print(counters[1])
counters[1] = nil                 -- delete
for key, value in pairs(counters) do print(key, value) end

local events <close> = map.queue("/sys/fs/bpf/events", "I8")
events:push(1234)
print(events:pop())

Functions

array (pathname, keyspec, valuespec) Opens a pinned array map as a table.
close (proxy) Releases the map reference.
hash (pathname, keyspec, valuespec) Opens a pinned hash map as a table.
info (proxy) Returns the map properties, as bpf map info.
lru_hash (pathname, keyspec, valuespec) Opens a pinned LRU hash map as a table.
queue (pathname, valuespec) Opens a pinned queue map (FIFO).
stack (pathname, valuespec) Opens a pinned stack map (LIFO).

Class map_queue

map_queue:close () Releases the map reference.
map_queue:info () Returns the map properties, as bpf map info.
map_queue:peek () Returns the next value, leaving it in the map.
map_queue:pop () Removes and returns the next value.
map_queue:push (value) Inserts a value.

Functions in detail

array (pathname, keyspec, valuespec)
Opens a pinned array map as a table. Keys are the u32 indices of the array. Array elements always exist: every index below max_entries reads a value, zero-filled if never set, and assigning nil raises EINVAL; write a zero value instead.

Parameters

Returns

    map_hash the table proxy

Raises

Error if the map cannot be opened or a spec does not match its sizes.
close (proxy)
Releases the map reference. Also wired as the proxy’s __close metamethod.

Parameters

  • proxy map_hash the table proxy
hash (pathname, keyspec, valuespec)
Opens a pinned hash map as a table. Assigning a key the map does not hold raises E2BIG once the map is full.

Parameters

Returns

    map_hash the table proxy

Raises

Error if the map cannot be opened or a spec does not match its sizes.
info (proxy)
Returns the map properties, as bpf map info.

Parameters

  • proxy map_hash the table proxy

Returns

    table type, key_size, value_size and max_entries
lru_hash (pathname, keyspec, valuespec)
Opens a pinned LRU hash map as a table.

Parameters

Returns

    map_hash the table proxy

Raises

Error if the map cannot be opened or a spec does not match its sizes.
queue (pathname, valuespec)
Opens a pinned queue map (FIFO).

Parameters

Returns

    map_queue the map object

Raises

Error if the map cannot be opened or the spec does not match its value size.
stack (pathname, valuespec)
Opens a pinned stack map (LIFO).

Parameters

Returns

    map_queue the map object

Raises

Error if the map cannot be opened or the spec does not match its value size.

Class map_queue in detail

Keyless map object, as returned by queue and stack.
map_queue:close ()
Releases the map reference. Also wired as the object’s __close metamethod.
map_queue:info ()
Returns the map properties, as bpf map info.

Returns

    table type, key_size, value_size and max_entries
map_queue:peek ()
Returns the next value, leaving it in the map.

Returns

    the value, or nil if the map is empty

Raises

Error if the operation fails.
map_queue:pop ()
Removes and returns the next value.

Returns

    the value, or nil if the map is empty

Raises

Error if the operation fails.
map_queue:push (value)
Inserts a value.

Parameters

  • value the value to insert, as the spec encodes it

Returns

    boolean false if the map is full, true otherwise

Raises

Error if the operation fails.