Module eco.socket

socket functions.

Functions

socket (family, domain[, protocol=0[, options]]) Create a socket.
socketpair (family, domain[, protocol=0[, options]]) Create a pair of connected sockets.
tcp () Create a TCP (IPv4) stream socket.
tcp6 () Create a TCP (IPv6) stream socket.
udp () Create a UDP (IPv4) datagram socket.
udp6 () Create a UDP (IPv6) datagram socket.
icmp () Create an ICMP (IPv4) socket.
icmp6 () Create an ICMP (IPv6) socket.
unix () Create a Unix stream socket.
unix_dgram () Create a Unix datagram socket.
netlink (protocol) Create a netlink raw socket.
listen_tcp ([ipaddr], port[, options]) Create, bind and listen on a TCP socket.
connect_tcp (ipaddr, port[, options]) Create and connect a TCP socket.
listen_udp ([ipaddr], port[, options]) Create and bind a UDP socket.
connect_udp (ipaddr, port[, options]) Create and connect a UDP socket.
listen_unix (path[, options]) Create, bind and listen on a Unix domain socket.
connect_unix (server_path[, local_path]) Connect to a Unix domain socket.
is_ip_address (addr) Check if a string is an IPv4/IPv6 address.
is_ipv4_address (ip) Check whether a string is a valid IPv4 address.
is_ipv6_address (ip) Check whether a string is a valid IPv6 address.
inet_aton (ip) Convert an IPv4 address string to an integer.
inet_ntoa (addr) Convert an IPv4 address integer to a string.
inet_ntop (family, addr) Convert a binary network address to presentation format.
inet_pton (family, ip) Convert a presentation format address to binary.
if_nametoindex (ifname) Convert interface name to interface index.
if_indextoname (Interface) Convert interface index to interface name.
htonl (n) Convert 32-bit integer from host to network byte order.
htons (n) Convert 16-bit integer from host to network byte order.
ntohl (n) Convert 32-bit integer from network to host byte order.
ntohs (n) Convert 16-bit integer from network to host byte order.

Fields

AF_UNSPEC Address family: unspecified.
AF_INET Address family: IPv4.
AF_INET6 Address family: IPv6.
AF_UNIX Address family: Unix domain sockets.
AF_PACKET Address family: packet interface (link layer).
AF_NETLINK Address family: netlink.
SOCK_DGRAM Socket type: datagram.
SOCK_STREAM Socket type: stream.
SOCK_RAW Socket type: raw.
IPPROTO_ICMP Protocol number: ICMP (IPv4).
IPPROTO_ICMPV6 Protocol number: ICMPv6.
IPPROTO_TCP Protocol number: TCP.
IPPROTO_UDP Protocol number: UDP.

Class socket

socket:getfd () Get underlying file descriptor.
socket:close () Close the socket.
socket:closed () Check whether the socket is closed.
socket:setoption (name, value) Set a socket option.
socket:getsockname () Get local socket address.
socket:getpeername () Get peer socket address.
socket:bind () Bind to a local address.
socket:listen ([backlog]) Start listening (server sockets).
socket:connect () Connect to a remote address.
socket:accept ([timeout]) Accept an incoming connection.
socket:send (data[, timeout]) Send data on a connected stream socket.
socket:write () Alias of socket:send.
socket:sendto (data) Send a datagram.
socket:sendfile (path[, len[, offset=0]]) Send file contents on a connected stream socket.
socket:recv () Alias of socket:read.
socket:read () See read
socket:recvfull () Alias of socket:readfull.
socket:readfull () See readfull
socket:readuntil () See readuntil
socket:recvfrom (n[, timeout]) Receive a datagram.


Functions

socket (family, domain[, protocol=0[, options]])
Create a socket.

Parameters:

  • family int Address family (e.g. socket.AF_INET).
  • domain int Socket type (e.g. socket.SOCK_STREAM).
  • protocol int Protocol number. (default 0)
  • options table

    Options:

    • reuseaddr (boolean)
    • reuseport (boolean)
    • ipv6_v6only (boolean)
    • mark (int)
    • device (string) bind to device name
    (optional)

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
socketpair (family, domain[, protocol=0[, options]])
Create a pair of connected sockets.

Parameters:

  • family int
  • domain int
  • protocol int (default 0)
  • options table See socket. (optional)

Returns:

  1. socket sock1
  2. socket sock2

Or

  1. nil On failure.
  2. string Error message.
tcp ()
Create a TCP (IPv4) stream socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
tcp6 ()
Create a TCP (IPv6) stream socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
udp ()
Create a UDP (IPv4) datagram socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
udp6 ()
Create a UDP (IPv6) datagram socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
icmp ()
Create an ICMP (IPv4) socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
icmp6 ()
Create an ICMP (IPv6) socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
unix ()
Create a Unix stream socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
unix_dgram ()
Create a Unix datagram socket.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
netlink (protocol)
Create a netlink raw socket.

Parameters:

  • protocol int Netlink protocol.

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
listen_tcp ([ipaddr], port[, options])
Create, bind and listen on a TCP socket.

Parameters:

  • ipaddr string Local address (nil means ANY). (optional)
  • port int Local port.
  • options table

    Options:

    • ipv6 (boolean) use IPv6 family
    • backlog (int)
    • tcp_nodelay (boolean)
    • keepalive (boolean)
    • tcp_keepidle (int)
    • tcp_keepcnt (int)
    • tcp_keepintvl (int)
    • tcp_fastopen (int)
    • plus options accepted by socket
    (optional)

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
connect_tcp (ipaddr, port[, options])
Create and connect a TCP socket.

Address family is inferred from ipaddr.

Parameters:

  • ipaddr string Remote IPv4/IPv6 address.
  • port int Remote port.
  • options table Options accepted by socket. (optional)

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
listen_udp ([ipaddr], port[, options])
Create and bind a UDP socket.

Parameters:

  • ipaddr string Local address. (optional)
  • port int Local port.
  • options table Options (ipv6 + options accepted by socket). (optional)

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
connect_udp (ipaddr, port[, options])
Create and connect a UDP socket.

Parameters:

  • ipaddr string Remote address.
  • port int Remote port.
  • options table Options accepted by socket. (optional)

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
listen_unix (path[, options])
Create, bind and listen on a Unix domain socket.

Parameters:

  • path string Filesystem path.
  • options table Options (backlog + options accepted by socket). (optional)

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
connect_unix (server_path[, local_path])
Connect to a Unix domain socket.

Parameters:

  • server_path string Server socket path.
  • local_path string Optional local bind path. (optional)

Returns:

    socket sock

Or

  1. nil On failure.
  2. string Error message.
is_ip_address (addr)
Check if a string is an IPv4/IPv6 address.

Parameters:

Returns:

    boolean ok
is_ipv4_address (ip)
Check whether a string is a valid IPv4 address.

Parameters:

Returns:

    boolean
is_ipv6_address (ip)
Check whether a string is a valid IPv6 address.

Parameters:

Returns:

    boolean
inet_aton (ip)
Convert an IPv4 address string to an integer.

This is a wrapper around inet_aton(3) and returns in_addr.s_addr.

Parameters:

  • ip string IPv4 address string.

Returns:

    int IPv4 address as an integer (network byte order).
inet_ntoa (addr)
Convert an IPv4 address integer to a string.

Parameters:

  • addr int IPv4 address as an integer (network byte order).

Returns:

    string IPv4 address string.
inet_ntop (family, addr)
Convert a binary network address to presentation format.

Parameters:

Returns:

    string Address string.

Or

    nil On failure.
inet_pton (family, ip)
Convert a presentation format address to binary.

Parameters:

Returns:

    string Binary address.

Or

    nil On failure.
if_nametoindex (ifname)
Convert interface name to interface index.

Parameters:

  • ifname string Interface name.

Returns:

    int Interface index.

Or

    nil If interface does not exist.
if_indextoname (Interface)
Convert interface index to interface name.

Parameters:

  • Interface int index.

Returns:

    string Interface name.
htonl (n)
Convert 32-bit integer from host to network byte order.

Parameters:

  • n int

Returns:

    int
htons (n)
Convert 16-bit integer from host to network byte order.

Parameters:

  • n int

Returns:

    int
ntohl (n)
Convert 32-bit integer from network to host byte order.

Parameters:

  • n int

Returns:

    int
ntohs (n)
Convert 16-bit integer from network to host byte order.

Parameters:

  • n int

Returns:

    int

Fields

AF_UNSPEC
Address family: unspecified.
AF_INET
Address family: IPv4.
AF_INET6
Address family: IPv6.
AF_UNIX
Address family: Unix domain sockets.
AF_PACKET
Address family: packet interface (link layer).
AF_NETLINK
Address family: netlink.
SOCK_DGRAM
Socket type: datagram.
SOCK_STREAM
Socket type: stream.
SOCK_RAW
Socket type: raw.
IPPROTO_ICMP
Protocol number: ICMP (IPv4).
IPPROTO_ICMPV6
Protocol number: ICMPv6.
IPPROTO_TCP
Protocol number: TCP.
IPPROTO_UDP
Protocol number: UDP.

Class socket

Socket object returned by this module.
socket:getfd ()
Get underlying file descriptor.

Returns:

    int fd
socket:close ()
Close the socket.
socket:closed ()
Check whether the socket is closed.

Returns:

    boolean
socket:setoption (name, value)
Set a socket option.

Supported option names: reuseaddr, reuseport, keepalive, broadcast, mark, bindtodevice, tcp_nodelay, tcp_keepidle, ...

Parameters:

  • name string Option name.
  • value any Option value.

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
socket:getsockname ()

Get local socket address.

Returned address is a table. Typical fields:

  • family
  • IPv4/IPv6: ipaddr, port
  • Unix: path
  • Netlink: pid

Returns:

    table addr

Or

  1. nil On failure.
  2. string Error message.
socket:getpeername ()
Get peer socket address.

Address table format is the same as socket:getsockname.

Returns:

    table addr

Or

  1. nil On failure.
  2. string Error message.
socket:bind ()

Bind to a local address.

Arguments depend on socket family:

  • IPv4/IPv6: bind(ipaddr, port) (ipaddr can be nil for ANY)
  • Unix: bind(path)
  • Netlink: bind(groups?, pid?)
  • Packet: bind({ ifindex=..., ifname=... })

Returns:

    socket self

Or

  1. nil On failure.
  2. string Error message.
socket:listen ([backlog])
Start listening (server sockets).

Parameters:

  • backlog int Listen backlog. (optional)

Returns:

    socket self

Or

  1. nil On failure.
  2. string Error message.
socket:connect ()
Connect to a remote address.

Arguments depend on socket family (same as socket:bind).

Returns:

    socket self

Or

  1. nil On failure.
  2. string Error message.
socket:accept ([timeout])
Accept an incoming connection.

Parameters:

  • timeout number Timeout in seconds. (optional)

Returns:

  1. socket client Accepted client socket.
  2. socket A new socket object.
  3. table Peer address table.

Or

  1. nil On failure.
  2. string Error message.
socket:send (data[, timeout])
Send data on a connected stream socket.

This method serializes concurrent writers using an internal mutex.

Parameters:

  • data string Data to send.
  • timeout number Timeout in seconds (optional)

Returns:

    int Bytes sent.

Or

  1. nil On failure.
  2. string Error message.
socket:write ()
Alias of socket:send.
socket:sendto (data)
Send a datagram.

For UDP/RAW sockets, destination address is provided after data. Arguments follow the same conventions as socket:connect.

Parameters:

Returns:

    int Total bytes sent.

Or

  1. nil On failure.
  2. string Error message.
socket:sendfile (path[, len[, offset=0]])
Send file contents on a connected stream socket.

Parameters:

  • path string File path.
  • len int Bytes to send. (optional)
  • offset int File offset. (default 0)

Returns:

    int Bytes sent.

Or

  1. nil On failure.
  2. string Error message.
socket:recv ()
Alias of socket:read.
socket:read ()
See read
socket:recvfull ()
Alias of socket:readfull.
socket:readfull ()
See readfull
socket:readuntil ()
See readuntil
socket:recvfrom (n[, timeout])
Receive a datagram.

Parameters:

  • n int Max bytes to receive.
  • timeout number Timeout in seconds. (optional)

Returns:

  1. string data
  2. table Peer address.

Or

  1. nil On failure.
  2. string Error message.
generated by LDoc 1.5.0 Last updated 2026-04-09 14:48:22