Module socket

Low-level Lua interface for kernel networking sockets.

This library provides support for creating and managing various types of sockets within the Linux kernel, enabling network communication directly from Lua scripts running in kernel space. It is inspired by Chengzhi Tan's GSoC project.

It allows operations such as creating sockets, binding, listening, connecting, sending, and receiving data. The library also exposes constants for address families, socket types, IP protocols, and message flags.

For higher-level IPv4 TCP/UDP socket operations with string-based IP addresses (e.g., "127.0.0.1"), consider using the socket.inet library.

See also:

Functions

accept (self[, flags=0]) Accepts a connection on a listening socket.
bind (addr[, port]) Binds the socket to a local address.
close () Closes the socket.
connect (addr[, port[, flags=0]]) Initiates a connection on a socket.
getpeername () Gets the address of the peer to which the socket is connected.
getsockname () Gets the local address to which the socket is bound.
listen ([backlog]) Puts a connection-oriented socket into the listening state.
receive (length[, flags=0[, from=false]]) Receives a message from the socket.
send (message[, addr[, port]]) Sends a message through the socket.

socket

new (family, type, protocol) Creates a new socket object.


Functions

accept (self[, flags=0])
Accepts a connection on a listening socket. This function is used with connection-oriented sockets (e.g., SOCK_STREAM) that have been put into the listening state by sock:listen().

Parameters:

  • self socket listening socket object.
  • flags integer Optional flags to apply to the newly accepted socket (e.g., linux.socket.sock.NONBLOCK, linux.socket.sock.CLOEXEC). (default 0)

Returns:

    socket A new socket object representing the accepted connection.

Raises:

Error if the accept operation fails.
bind (addr[, port])
Binds the socket to a local address. This is typically used on the server side before calling listen() or on connectionless sockets to specify a local port/interface for receiving.

Parameters:

  • addr integer or string

    local address to bind to. Interpretation depends on socket.sk.sk_family:

    • AF_INET (IPv4): An integer representing the IPv4 address (e.g., from net.aton()). Use 0 (or net.aton("0.0.0.0")) to bind to all available interfaces. The port argument is also required.
    • AF_PACKET: An integer representing the ethernet protocol in host byte order (e.g., 0x0003 for ETH_P_ALL, 0x88CC for ETH_P_LLDP) The port argument is also required.
    • Other families: A packed string directly representing parts of the family-specific address structure.
  • port integer local port or interface index. - AF_INET: TCP/UDP port number. - AF_PACKET: Network interface index (e.g., from linux.ifindex("eth0")). (optional)

Returns:

    nil

Raises:

Error if the bind operation fails (e.g., address already in use, invalid address).

See also:

Usage:

    -- Bind TCP/IPv4 socket to localhost, port 8080
tcp_server_sock:bind(net.aton("127.0.0.1"), 8080)

-- Bind AF_PACKET socket to protocol ETH_P_LLDP on a specific interface
af_packet_sock:bind(0x88CC, linux.ifindex("eth0"))
close ()
Closes the socket. This shuts down the socket for both reading and writing and releases associated kernel resources. This method is also called automatically when the socket object is garbage collected or via Lua 5.4's to-be-closed mechanism.

Returns:

    nil
connect (addr[, port[, flags=0]])
Initiates a connection on a socket. This is typically used by client sockets to establish a connection to a server. For datagram sockets, this sets the default destination address for send and the only address from which datagrams are received.

Parameters:

  • addr integer or string

    destination address to connect to. Interpretation depends on socket.sk.sk_family:

    • AF_INET (IPv4): An integer representing the IPv4 address (e.g., from net.aton()). The port argument is also required.
    • Other families: A packed string representing the family-specific destination address.
  • port integer destination port number (required and used only if the family is AF_INET). (optional)
  • flags integer Optional connection flags. (default 0)

Returns:

    nil

Raises:

Error if the connect operation fails (e.g., connection refused, host unreachable).

Usage:

    tcp_client_sock:connect(net.aton("192.168.1.100"), 80)
getpeername ()
Gets the address of the peer to which the socket is connected. This is typically used with connection-oriented sockets after a connection has been established, or with connectionless sockets after connect() has been called to set a default peer.

Returns:

  1. integer or string

    addr peer's address.

    • For AF_INET: An integer representing the IPv4 address (can be converted with net.ntoa()).
    • For other families: A packed string representing the peer's address.
  2. integer port If the family is AF_INET, the peer's port number.

Raises:

Error if the operation fails (e.g., socket not connected).

Usage:

    local peer_ip_int, peer_port = connected_socket:getpeername()
if connected_socket.sk.sk_family == linux.socket.af.INET then print("Connected to " .. net.ntoa(peer_ip_int) .. ":" .. peer_port) end
getsockname ()
Gets the local address to which the socket is bound.

Returns:

  1. integer or string

    addr local address.

    • For AF_INET: An integer representing the IPv4 address (can be converted with net.ntoa()).
    • For other families: A packed string representing the local address.
  2. integer port If the family is AF_INET, the local port number.

Raises:

Error if the operation fails.

Usage:

    local local_ip_int, local_port = my_socket:getsockname()
if my_socket.sk.sk_family == linux.socket.af.INET then print("Bound to " .. net.ntoa(local_ip_int) .. ":" .. local_port) end
listen ([backlog])
Puts a connection-oriented socket into the listening state. This is required for server sockets (e.g., SOCK_STREAM) to be able to accept incoming connections.

Parameters:

  • backlog integer maximum length of the queue for pending connections. If omitted, a system-dependent default (e.g., SOMAXCONN) is used. (optional)

Returns:

    nil

Raises:

Error if the listen operation fails (e.g., socket not bound, invalid state).

Usage:

    tcp_server_sock:listen(10)
receive (length[, flags=0[, from=false]])
Receives a message from the socket.

Parameters:

  • length integer maximum number of bytes to receive.
  • flags integer Optional message flags (e.g., linux.socket.msg.PEEK). See the linux.socket.msg table for available flags. These can be OR'd together. (default 0)
  • from boolean If true, the function also returns the sender's address and port (for AF_INET). This is typically used with connectionless sockets (SOCK_DGRAM). (default false)

Returns:

  1. string received message (as a string of bytes).
  2. integer or string addr If from is true, the sender's address. - For AF_INET: An integer representing the IPv4 address (can be converted with net.ntoa()). - For other families: A packed string representing the sender's address.
  3. integer port If from is true and the family is AF_INET, the sender's port number.

Raises:

Error if the receive operation fails.

See also:

Usage:

    -- For a connected TCP socket:
local data = tcp_conn_sock:receive(1024)
if data then print("Received:", data) end

-- For a UDP socket, getting sender info:
local data, sender_ip_int, sender_port = udp_sock:receive(1500, 0, true)
if data then print("Received from " .. net.ntoa(sender_ip_int) .. ":" .. sender_port .. ": " .. data) end
send (message[, addr[, port]])
Sends a message through the socket.

For connection-oriented sockets (SOCK_STREAM), addr and port are usually omitted as the connection is already established. For connectionless sockets (SOCK_DGRAM), addr and port (if applicable for the address family) specify the destination.

Parameters:

  • message string message to send.
  • addr integer or string

    destination address.

    • For AF_INET (IPv4) sockets: An integer representing the IPv4 address (e.g., from net.aton()).
    • For other address families (e.g., AF_PACKET): A packed string representing the destination address (e.g., MAC address for AF_PACKET). The exact format depends on the family.
    (optional)
  • port integer destination port number (required if addr is an IPv4 address for AF_INET). (optional)

Returns:

    integer number of bytes sent.

Raises:

Error if the send operation fails or if address parameters are incorrect for the socket type.

See also:

Usage:

    -- For a connected TCP socket:
local bytes_sent = tcp_conn_sock:send("Hello, server!")

-- For a UDP socket (sending to 192.168.1.100, port 1234):
local bytes_sent = udp_sock:send("UDP packet", net.aton("192.168.1.100"), 1234)

socket

new (family, type, protocol)
Creates a new socket object. This function is the primary way to create a socket.

Parameters:

  • family integer address family (e.g., linux.socket.af.INET).
  • type integer socket type (e.g., linux.socket.sock.STREAM).
  • protocol integer protocol (e.g., linux.socket.ipproto.TCP). For AF_PACKET sockets, protocol is typically an ETH_P_* value in network byte order (e.g., linux.hton16(0x0003) for ETH_P_ALL).

Returns:

    socket A new socket object.

Raises:

Error if socket creation fails.

See also:

Usage:

    -- TCP/IPv4 socket
local tcp_sock = socket.new(linux.socket.af.INET, linux.socket.sock.STREAM, linux.socket.ipproto.TCP)
generated by LDoc 1.5.0 Last updated 2026-05-09 15:39:54