socket.lua File Reference

Go to the source code of this file.

Functions
_M	connect4 (address, port, laddress, lport)
	Create a TCP IPv4 socket connected to the specified address and port.
_M	connect6 (address, port, laddress, lport)
	Create a TCP IPv6 socket connected to the specified address and port.
_M	bind (host, port, backlog)
	Bind and listen on a host/port, returning a server socket.
_M	choose (table)
	Create a dispatcher function that selects and calls a handler from a table by name.
	getfd ()
	Return the file descriptor of the socket for the close-when-done sink.
	dirty ()
	Return the dirty state of the socket for the close-when-done sink.

Function Documentation

bind()

_M bind	(	host	,
		port	,
		backlog	)

Bind and listen on a host/port, returning a server socket.

Resolves the given host using DNS and iterates over the returned address records to create and bind either a TCP IPv4 or TCP IPv6 socket depending on the address family. The wildcard host "*" is mapped to "0.0.0.0". The socket is configured with SO_REUSEADDR before binding. If binding or listening fails for a candidate address the socket is closed and the next address is tried. The first successfully bound and listening socket is returned.

Parameters

host	(string) Hostname or IP address to bind to. Use "*" to bind all interfaces
port	(number) Port number to bind to
backlog	(number|nil) Maximum length of the pending connection queue passed to listen()

Returns

(userdata|nil) The bound and listening server socket, or nil on failure

(string|nil) Error message if the operation failed, or nil on success

-- Bind to all interfaces on port 8080
local server, err = socket.bind("*", 8080)
if not server then
    print("Bind failed: " .. err)
end
 
-- Bind to a specific address with custom backlog
local server, err = socket.bind("127.0.0.1", 9090, 32)

Note

Documentation generated by AI on 2026-03-03

choose()

_M choose

(

table

)

Create a dispatcher function that selects and calls a handler from a table by name.

Returns a closure that, when called, looks up a handler in the provided table by the given name key and invokes it with up to two optional arguments. If the first argument is not a string, it is treated as the first option argument and the key defaults to "default". Raises a level-3 error if the key is not found in the table.

Parameters

table

(table) A table mapping string keys to callable handler functions

Returns

(function) A dispatcher function with signature (name, opt1, opt2) where:

• name (string|nil): Key to look up in the table; if non-string, defaults to "default"
• opt1 (any): First argument passed to the selected handler
• opt2 (any): Second argument passed to the selected handler

-- Create a dispatcher over a table of strategies
local dispatcher = socket.choose(sinkt)
local sink = dispatcher("keep-open", sock)
 
-- Using the default strategy (name omitted / non-string first arg)
local sink = dispatcher(sock)

Note

Documentation generated by AI on 2026-03-03

connect4()

_M connect4	(	address	,
		port	,
		laddress	,
		lport	)

Create a TCP IPv4 socket connected to the specified address and port.

---

Wraps socket.connect() forcing the address family to "inet". An optional local address and port may be supplied for binding the local end of the connection before connecting.

Parameters

address	(string) Remote hostname or IPv4 address to connect to
port	(number) Remote port number to connect to
laddress	(string|nil) Local IPv4 address to bind to before connecting, or nil for any
lport	(number|nil) Local port to bind to before connecting, or nil for any

Returns

(userdata|nil) Connected TCP socket object, or nil on failure

(string|nil) Error message if the connection failed, or nil on success

See also

_M.connect6 for the IPv6 equivalent

Note

Documentation generated by AI on 2026-03-03

connect6()

_M connect6	(	address	,
		port	,
		laddress	,
		lport	)

Create a TCP IPv6 socket connected to the specified address and port.

Wraps socket.connect() forcing the address family to "inet6". An optional local address and port may be supplied for binding the local end of the connection before connecting.

Parameters

address	(string) Remote hostname or IPv6 address to connect to
port	(number) Remote port number to connect to
laddress	(string|nil) Local IPv6 address to bind to before connecting, or nil for any
lport	(number|nil) Local port to bind to before connecting, or nil for any

Returns

(userdata|nil) Connected TCP socket object, or nil on failure

(string|nil) Error message if the connection failed, or nil on success

See also

_M.connect4 for the IPv4 equivalent

Note

Documentation generated by AI on 2026-03-03

dirty()

dirty

(

)

Return the dirty state of the socket for the close-when-done sink.

Return the dirty state of the socket for the until-closed source.

Return the dirty state of the socket for the by-length source.

Return the dirty state of the socket for the keep-open sink.

Delegates to the underlying socket's dirty() method to indicate whether the socket has buffered data that has not yet been read. Used by LTN12 pipeline machinery to determine if the sink needs to be polled again.

Returns

(boolean) True if the socket has unread buffered data, false otherwise

Note

Documentation generated by AI on 2026-03-03

Delegates to the underlying socket's dirty() method to indicate whether the socket has buffered data that has not yet been read. Used by LTN12 pipeline machinery to determine if the source needs to be polled again.

Returns

(boolean) True if the socket has unread buffered data, false otherwise

Note

Documentation generated by AI on 2026-03-03

getfd()

getfd

(

)

Return the file descriptor of the socket for the close-when-done sink.

Return the file descriptor of the socket for the until-closed source.

Return the file descriptor of the socket for the by-length source.

Return the file descriptor of the socket for the keep-open sink.

Delegates to the underlying socket's getfd() method to expose the raw file descriptor. Used by LTN12 pipeline machinery and socket multiplexing (e.g., socket.select()) to identify the underlying OS socket handle.

Returns

(number) The raw file descriptor of the underlying socket

Note

Documentation generated by AI on 2026-03-03