Module eco.nl

Netlink sockets and helpers.

This module is a small wrapper around eco.socket's netlink sockets and provides low-level message/attribute helpers and Linux netlink constants.

The most common entry point is nl.open, which returns a socket object with convenience methods.

Many constants from Linux headers are also exported:

  • Netlink message type: NLMSG_*
  • Netlink message flag: NLM_F_*
  • Netlink protocol family: NETLINK_*

Functions

open (protocol) Create a netlink socket.
attr_get_u8 (attr) Decode an attribute whose payload is an unsigned 8-bit integer.
attr_get_s8 (attr) Decode an attribute whose payload is a signed 8-bit integer.
attr_get_u16 (attr) Decode an attribute whose payload is an unsigned 16-bit integer.
attr_get_s16 (attr) Decode an attribute whose payload is a signed 16-bit integer.
attr_get_u32 (attr) Decode an attribute whose payload is an unsigned 32-bit integer.
attr_get_s32 (attr) Decode an attribute whose payload is a signed 32-bit integer.
attr_get_u64 (attr) Decode an attribute whose payload is an unsigned 64-bit integer.
attr_get_s64 (attr) Decode an attribute whose payload is a signed 64-bit integer.
attr_get_str (attr) Decode an attribute whose payload is a NUL-terminated string.
attr_get_payload (attr) Get the raw payload bytes of an attribute.
parse_attr_nested (nest) Parse attributes from a nested attribute.
nlmsg (type, flags[, seq=0[, size=4096]]) Create a new netlink message builder.
nlmsg_ker (data) Create a parser for a received netlink datagram.

Class nlsocket

nlsocket:bind (groups[, pid]) Bind the netlink socket.
nlsocket:add_membership (group) Subscribe to a multicast group.
nlsocket:drop_membership (group) Unsubscribe from a multicast group.
nlsocket:send (msg) Send a netlink message.
nlsocket:recv ([n=8192[, timeout]]) Receive data from the netlink socket.
nlsocket:request_ack (msg[, on_error]) Send a request and wait for an ACK (NLMSG_ERROR with error=0).
nlsocket:request_dump (msg[, on_msg[, on_error]]) Send a request and iterate reply messages until NLMSG_DONE.
nlsocket:recv_messages ([on_msg[, on_error[, n=8192[, timeout]]]]) Receive and dispatch netlink messages in a loop.
nlsocket:close () Close the socket.

Class nlmsg_ker

nlmsg_ker:next () Iterate to the next netlink message in the received datagram.
nlmsg_ker:payload () Get the payload of the current netlink message.
nlmsg_ker:parse_attr (offset) Parse netlink attributes from the current message.
nlmsg_ker:parse_error () Parse an NLMSG_ERROR message.

Class nlmsg

nlmsg:binary () Serialize a message builder to a binary string.
nlmsg:put (data) Append raw bytes to the message payload.
nlmsg:put_attr (type, value) Append a netlink attribute with an arbitrary payload.
nlmsg:put_attr_flag (type) Append a flag attribute (attribute with zero-length payload).
nlmsg:put_attr_u8 (type, value) Append an attribute whose payload is an unsigned 8-bit integer.
nlmsg:put_attr_u16 (type, value) Append an attribute whose payload is an unsigned 16-bit integer.
nlmsg:put_attr_u32 (type, value) Append an attribute whose payload is an unsigned 32-bit integer.
nlmsg:put_attr_u64 (type, value) Append an attribute whose payload is an unsigned 64-bit integer.
nlmsg:put_attr_str (type, value) Append an attribute whose payload is a string (without trailing NUL).
nlmsg:put_attr_strz (type, value) Append an attribute whose payload is a NUL-terminated string.
nlmsg:put_attr_nest_start (type) Start a nested attribute.
nlmsg:put_attr_nest_end () End the current nested attribute.


Functions

open (protocol)
Create a netlink socket.

Parameters:

  • protocol int Netlink protocol.

Returns:

    nlsocket

Or

  1. nil On failure.
  2. string Error message.

Usage:

    local nl = require 'eco.nl'

local sock<close>, err = nl.open(nl.NETLINK_ROUTE)
assert(sock, err)

-- Build a request.
local msg = nl.nlmsg(0, 0)
msg:put('hello')
assert(sock:send(msg))

-- Receive and iterate.
local rx = assert(sock:recv())
local hdr = rx:next()
if hdr then
    print('type:', hdr.type)
end
attr_get_u8 (attr)
Decode an attribute whose payload is an unsigned 8-bit integer.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_s8 (attr)
Decode an attribute whose payload is a signed 8-bit integer.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_u16 (attr)
Decode an attribute whose payload is an unsigned 16-bit integer.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_s16 (attr)
Decode an attribute whose payload is a signed 16-bit integer.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_u32 (attr)
Decode an attribute whose payload is an unsigned 32-bit integer.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_s32 (attr)
Decode an attribute whose payload is a signed 32-bit integer.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_u64 (attr)
Decode an attribute whose payload is an unsigned 64-bit integer.

Values larger than INT64_MAX are clamped to INT64_MAX because Lua integers are signed.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_s64 (attr)
Decode an attribute whose payload is a signed 64-bit integer.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    int value
attr_get_str (attr)
Decode an attribute whose payload is a NUL-terminated string.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    string value
attr_get_payload (attr)
Get the raw payload bytes of an attribute.

Parameters:

  • attr string Raw attribute bytes.

Returns:

    string payload
parse_attr_nested (nest)
Parse attributes from a nested attribute.

The returned table is indexed by attribute type. Each value is a raw attribute binary string (including header), compatible with attr_get_*.

Parameters:

  • nest string Raw attribute bytes.

Returns:

    table attrs
nlmsg (type, flags[, seq=0[, size=4096]])
Create a new netlink message builder.

Parameters:

  • type int Netlink message type.
  • flags int Netlink flags bitmask.
  • seq integer Sequence number. (default 0)
  • size integer Buffer size hint (bytes) for payload/attributes. (default 4096)

Returns:

    nlmsg msg
nlmsg_ker (data)
Create a parser for a received netlink datagram.

The returned object can iterate over all messages within the datagram.

Parameters:

  • data string Binary datagram returned by a netlink socket.

Returns:

    nlmsg_ker msg

Class nlsocket

Netlink socket object returned by nl.open.

This is a thin wrapper around a netlink socket returned by eco.socket.netlink. The object also supports Lua 5.4 to-be-closed variables via the __close metamethod.

nlsocket:bind (groups[, pid])
Bind the netlink socket.

Parameters:

  • groups int Multicast group bitmap.
  • pid int Local PID to bind. (optional)

Returns:

    boolean true On success

Or

  1. nil On failure.
  2. string Error message.
nlsocket:add_membership (group)
Subscribe to a multicast group.

Parameters:

  • group int Multicast group id.

Returns:

    boolean true On success

Or

  1. nil On failure.
  2. string Error message.
nlsocket:drop_membership (group)
Unsubscribe from a multicast group.

Parameters:

  • group int Multicast group id.

Returns:

    boolean true On success

Or

  1. nil On failure.
  2. string Error message.
nlsocket:send (msg)
Send a netlink message.

Parameters:

Returns:

    int Bytes sent.

Or

  1. nil On failure.
  2. string Error message.
nlsocket:recv ([n=8192[, timeout]])
Receive data from the netlink socket.

The return value is a message parser created by nl.nlmsg_ker. The parser may contain multiple netlink messages; iterate them with nlmsg_ker:next.

Parameters:

  • n integer Max bytes to read. (default 8192)
  • timeout number Timeout in seconds. (optional)

Returns:

    nlmsg_ker

Or

  1. nil On failure.
  2. string Error message.
nlsocket:request_ack (msg[, on_error])
Send a request and wait for an ACK (NLMSG_ERROR with error=0).

Parameters:

  • msg nlmsg Request message.
  • on_error function Optional mapper on_error(errno)->string. (optional)

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
nlsocket:request_dump (msg[, on_msg[, on_error]])
Send a request and iterate reply messages until NLMSG_DONE.

Callback return conventions: - true: stop early and return success - false, err: stop and return error - nil: continue

Parameters:

  • msg nlmsg Request message.
  • on_msg function Callback on_msg(reply, nlh). (optional)
  • on_error function Optional mapper on_error(errno)->string. (optional)

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
nlsocket:recv_messages ([on_msg[, on_error[, n=8192[, timeout]]]])
Receive and dispatch netlink messages in a loop.

This is intended for event subscription sockets that only receive multicast notifications.

Callback return conventions: - true: stop loop and return success - false, err: stop loop and return error - nil: continue

Parameters:

  • on_msg function Callback on_msg(reply, nlh). (optional)
  • on_error function Optional mapper on_error(errno)->string. (optional)
  • n integer Max bytes to read per recv. (default 8192)
  • timeout number Timeout in seconds for each recv. (optional)

Returns:

    boolean true When callback stops loop with true.

Or

  1. nil On failure.
  2. string Error message.
nlsocket:close ()
Close the socket.

Class nlmsg_ker

Netlink message parser returned by nl.nlmsg_ker.

A single received datagram may contain multiple netlink messages. Call nlmsg_ker:next to iterate, then use nlmsg_ker:payload, nlmsg_ker:parse_attr, etc. to inspect the current message.

nlmsg_ker:next ()
Iterate to the next netlink message in the received datagram.

The returned table contains header fields for the current message. When there are no more messages, returns nil.

Returns:

    table or nil hdr Header table with fields: type, flags, seq, pid.
nlmsg_ker:payload ()
Get the payload of the current netlink message.

The current message is the one most recently selected by nlmsg_ker:next.

Returns:

    string payload

Or

  1. nil On failure.
  2. string Error message.
nlmsg_ker:parse_attr (offset)
Parse netlink attributes from the current message.

This parses the payload region starting at offset and returns a table indexed by attribute type. Each value is a binary string representing the struct nlattr (including header).

Use the module-level accessors (e.g. attr_get_u32, attr_get_str) to decode the returned attributes.

Parameters:

  • offset int Byte offset within the message payload where attributes start.

Returns:

    table attrs

Or

  1. nil On failure.
  2. string Error message.
nlmsg_ker:parse_error ()
Parse an NLMSG_ERROR message.

On success, returns the error field from struct nlmsgerr. Typically, 0 means ACK/success; a negative value is -errno.

Returns:

    int errcode

Or

  1. nil On failure.
  2. string Error message.

Class nlmsg

Netlink message builder returned by nl.nlmsg.

Use the put* methods to append payload and attributes.

nlmsg:binary ()
Serialize a message builder to a binary string.

Returns:

    string data
nlmsg:put (data)
Append raw bytes to the message payload.

Parameters:

  • data string Bytes to append.

Returns:

    nlmsg self
nlmsg:put_attr (type, value)
Append a netlink attribute with an arbitrary payload.

Parameters:

  • type int Attribute type.
  • value string Attribute payload bytes.

Returns:

    nlmsg self
nlmsg:put_attr_flag (type)
Append a flag attribute (attribute with zero-length payload).

Parameters:

  • type int Attribute type.

Returns:

    nlmsg self
nlmsg:put_attr_u8 (type, value)
Append an attribute whose payload is an unsigned 8-bit integer.

Parameters:

  • type int Attribute type.
  • value int Value.

Returns:

    nlmsg self
nlmsg:put_attr_u16 (type, value)
Append an attribute whose payload is an unsigned 16-bit integer.

Parameters:

  • type int Attribute type.
  • value int Value.

Returns:

    nlmsg self
nlmsg:put_attr_u32 (type, value)
Append an attribute whose payload is an unsigned 32-bit integer.

Parameters:

  • type int Attribute type.
  • value int Value.

Returns:

    nlmsg self
nlmsg:put_attr_u64 (type, value)
Append an attribute whose payload is an unsigned 64-bit integer.

Note: if Lua integers are 32-bit on the current build, values outside the 32-bit range may lose precision.

Parameters:

  • type int Attribute type.
  • value int Value.

Returns:

    nlmsg self
nlmsg:put_attr_str (type, value)
Append an attribute whose payload is a string (without trailing NUL).

This uses strlen() and therefore cannot be used for strings containing embedded \0 bytes.

Parameters:

  • type int Attribute type.
  • value string String value.

Returns:

    nlmsg self
nlmsg:put_attr_strz (type, value)
Append an attribute whose payload is a NUL-terminated string.

This uses strlen() and appends the terminating NUL.

Parameters:

  • type int Attribute type.
  • value string String value.

Returns:

    nlmsg self
nlmsg:put_attr_nest_start (type)
Start a nested attribute.

After calling this, subsequent attributes appended to the message will be counted into the nested attribute's length until nlmsg:put_attr_nest_end is called.

Note: this implementation tracks a single active nest level.

Parameters:

  • type int Attribute type.

Returns:

    nlmsg self
nlmsg:put_attr_nest_end ()
End the current nested attribute.

Returns:

    nlmsg self
generated by LDoc 1.5.0 Last updated 2026-04-09 14:48:22