Module posix.sys.socket

BSD Sockets.

Where supported by the underlying system, functions and constants to create, connect and communicate over BSD sockets. If the module loads successfully, but there is no kernel support, then posix.sys.socket.version will be set, but the unsupported APIs will be nil.

Functions

accept (fd) Accept a connection on a socket.
bind (fd, addr) Bind an address to a socket.
connect (fd, addr) Initiate a connection on a socket.
getaddrinfo (host, service[, hints]) Network address and service translation.
getpeername (sockfd) Get socket peer name.
getsockname (sockfd) Get socket name.
getsockopt (fd, level, name) Get options on sockets.
if_nametoindex (ifname) Get network interface index by name.
listen (fd, backlog) Listen for connections on a socket.
recv (fd, count) Receive a message from a socket.
recvfrom (fd, count) Receive a message from a socket.
send (fd, buffer) Send a message from a socket.
sendto (fd, buffer, destination) Send a message from a socket.
setsockopt (fd, level, name, value1[, value2]) Get and set options on sockets.
shutdown (fd, how) Shut down part of a full-duplex connection.
socket (domain, type, options) Create an endpoint for communication.
socketpair (domain, socktype, options) Create a pair of connected sockets.

Tables

PosixAddrInfo Address information hints.
sockaddr Socket address.

Constants

posix.sys.socket Socket constants.


Functions

accept (fd)
Accept a connection on a socket.

Parameters:

  • fd int socket descriptor to act on

Returns:

  1. int connection descriptor
  2. table connection address, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

bind (fd, addr)
Bind an address to a socket.

Parameters:

  • fd int socket descriptor to act on
  • addr sockaddr socket address

Returns:

    int 0, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

connect (fd, addr)
Initiate a connection on a socket.

Parameters:

  • fd int socket descriptor to act on
  • addr sockaddr socket address

Returns:

    int 0, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

getaddrinfo (host, service[, hints])
Network address and service translation.

Parameters:

  • host string name of a host. For IPv6, link-local addresses like 'ff02::1%eth0' are supported.
  • service string name of service
  • hints PosixAddrInfo table (optional)

Returns:

    list of sockaddr tables, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

      local sys_sock = require "posix.sys.socket"
  local res, errmsg, errcode = sys_sock.getaddrinfo ("www.lua.org", "http",
    { family = sys_sock.IF_INET, socktype = sys_sock.SOCK_STREAM }
)
getpeername (sockfd)
Get socket peer name.

Parameters:

  • sockfd int socket descriptor

Returns:

    sockaddr the address to which the socket sockfd is connected to, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    sa, err = posix.getpeername (sockfd)
getsockname (sockfd)
Get socket name.

Parameters:

  • sockfd int socket descriptor

Returns:

    sockaddr the current address to which the socket sockfd is bound, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    sa, err = posix.getsockname (sockfd)
getsockopt (fd, level, name)
Get options on sockets.

Parameters:

  • fd int socket descriptor
  • level int one of SOL_SOCKET, IPPROTO_IPV6, IPPROTO_TCP
  • name int option name, varies according to level value

Returns:

    the value of the requested socket option, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    local sys_sock = require "posix.sys.socket"
val, errmsg, errnum = sys_sock.getsockopt(
  sock, sys_sock.SOL_SOCKET, sys_sock.SO_SNDTIMEO
)
print('Send timeout ', val.tv_sec + val.tv_usec / 1000000)
if_nametoindex (ifname)
Get network interface index by name. Needed for packet sockets, since SO_BINDTODEVICE won't work on packet family.

Parameters:

  • ifname string interface name

Returns:

    int interface index, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    local sys_sock = require "posix.sys.socket"
ifindex, errmsg, errnum = sys_sock.if_nametoindex("eth0")
listen (fd, backlog)
Listen for connections on a socket.

Parameters:

  • fd int socket descriptor to act on
  • backlog int maximum length for queue of pending connections

Returns:

    int 0, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

recv (fd, count)
Receive a message from a socket.

Parameters:

  • fd int socket descriptor to act on
  • count int maximum number of bytes to receive

Returns:

    string received bytes, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

recvfrom (fd, count)
Receive a message from a socket.

Parameters:

  • fd int socket descriptor to act on
  • count int maximum number of bytes to receive

Returns:

  1. int received bytes
  2. sockaddr address of message source, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

send (fd, buffer)
Send a message from a socket.

Parameters:

  • fd int socket descriptor to act on
  • buffer string message bytes to send

Returns:

    int number of bytes sent, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

sendto (fd, buffer, destination)
Send a message from a socket.

Parameters:

  • fd int socket descriptor to act on
  • buffer string message bytes to send
  • destination sockaddr socket address

Returns:

    int number of bytes sent, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

setsockopt (fd, level, name, value1[, value2])
Get and set options on sockets.

Parameters:

  • fd int socket descriptor
  • level int one of SOL_SOCKET, IPPROTO_IPV6, IPPROTO_TCP
  • name int option name, varies according to level value
  • value1 option value to set
  • value2 some option names need an additional value (optional)

Returns:

    int 0, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    local sys_sock = require "posix.sys.socket"
ok, errmsg = sys_sock.setsockopt (
  sock, sys_sock.SOL_SOCKET, sys_sock.SO_SNDTIMEO, 1, 0
)
shutdown (fd, how)
Shut down part of a full-duplex connection.

Parameters:

  • fd int socket descriptor to act on
  • how int one of SHUT_RD, SHUT_WR or SHUT_RDWR

Returns:

    int 0, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    local sys_sock = require "posix.sys.socket"
ok, errmsg = sys_sock.shutdown (sock, sys_sock.SHUT_RDWR)
socket (domain, type, options)
Create an endpoint for communication.

Parameters:

  • domain int one of AF_INET, AF_INET6, AF_UNIX, AF_NETLINK or AF_PACKET
  • type int one of SOCK_STREAM, SOCK_DGRAM or SOCK_RAW
  • options int usually 0, but some socket types might implement other protocols.

Returns:

    int socket descriptor, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    local sys_sock = require "posix.sys.socket"
sockd = sys_sock.socket (sys_sock.AF_INET, sys_sock.SOCK_STREAM, 0)
socketpair (domain, socktype, options)
Create a pair of connected sockets.

Parameters:

  • domain int one of AF_INET, AF_INET6, AF_UNIX or AF_NETLINK
  • socktype int one of SOCK_STREAM, SOCK_DGRAM or SOCK_RAW
  • options int usually 0, but some socket types might implement other protocols.

Returns:

  1. int descriptor of one end of the socket pair
  2. int descriptor of the other end of the pair, if successful

Or

  1. nil
  2. string error message
  3. int errnum

See also:

Usage:

    local sys_sock = require "posix.sys.socket"
sockr, sockw = sys_sock.socketpair (sys_sock.AF_INET, sys_sock.SOCK_STREAM, 0)

Tables

PosixAddrInfo
Address information hints.

Fields:

  • family int one of AF_INET, AF_INET6, AF_UNIX, AF_NETLINK or AF_PACKET
  • flags int bitwise OR of zero or more of AI_ADDRCONFIG, AI_ALL, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_PASSIVE and AI_V4MAPPED
  • socktype int one of SOCK_STREAM, SOCK_DGRAM or SOCK_RAW
  • protocol int one of IPPROTO_TCP or IPPROTO_UDP
sockaddr
Socket address. All sockaddr tables have the family field, and depending on its value, also a subset of the following fields too.

Fields:

  • family int one of AF_INET, AF_INET6, AF_UNIX, AF_NETLINK or AF_PACKET
  • port int socket port number for AF_INET (and equivalently AF_INET6) family (optional)
  • addr string socket host address in correct format, for AF_INET family (optional)
  • socktype int one of SOCK_STREAM, SOCK_DGRAM or SOCK_RAW for AF_INET family (optional)
  • canonname string canonical name for service location, for AF_INET family (optional)
  • protocol int one of IPPROTO_TCP or IPPROTO_UDP, for AF_INET family (optional)
  • path string location in file system, for AF_UNIX family (optional)
  • pid int process identifier, for AF_NETLINK family (optional)
  • groups int process group owner identifier, for AF_NETLINK family (optional)
  • ifindex int interface index, for AF_PACKET family (optional)

Constants

posix.sys.socket
Socket constants. Any constants not available in the underlying system will be nil valued.

Fields:

  • AF_INET int IP protocol family
  • AF_INET6 int IP version 6
  • AF_NETLINK int Netlink protocol family
  • AF_PACKET int Packet protocol family
  • AF_UNIX int local to host
  • AF_UNSPEC int unspecified
  • AI_ADDRCONFIG int use host configuration for returned address type
  • AI_ALL int return IPv4 mapped and IPv6 addresses
  • AI_CANONNAME int request canonical name
  • AI_NUMERICHOST int don't use domain name resolution
  • AI_NUMERICSERV int don't use service name resolution
  • AI_PASSIVE int address is intended for bind
  • AI_V4MAPPED int IPv4 mapped addresses are acceptable
  • IPPROTO_ICMP int internet control message protocol
  • IPPROTO_IP int internet protocol
  • IPPROTO_IPV6 int IPv6 header
  • IPPROTO_TCP int transmission control protocol
  • IPPROTO_UDP int user datagram protocol
  • IPV6_JOIN_GROUP int
  • IPV6_LEAVE_GROUP int
  • IPV6_MULTICAST_HOPS int
  • IPV6_MULTICAST_IF int
  • IPV6_MULTICAST_LOOP int
  • IPV6_UNICAST_HOPS int
  • IPV6_V6ONLY int
  • NETLINK_AUDIT int auditing
  • NETLINK_CONNECTOR int
  • NETLINK_DNRTMSG int decnet routing messages
  • NETLINK_ECRYPTFS int
  • NETLINK_FIB_LOOKUP int
  • NETLINK_FIREWALL int firewalling hook
  • NETLINK_GENERIC int
  • NETLINK_IP6_FW int
  • NETLINK_ISCSI int open iSCSI
  • NETLINK_KOBJECT_UEVENT int kernel messages to userspace
  • NETLINK_NETFILTER int netfilter subsystem
  • NETLINK_NFLOG int netfilter/iptables ULOG
  • NETLINK_ROUTE int routing/device hook
  • NETLINK_SCSITRANSPORT int SCSI transports
  • NETLINK_SELINUX int SELinux event notifications
  • NETLINK_UNUSED int unused number
  • NETLINK_USERSOCK int reserved for user mode socket protocols
  • NETLINK_XFRM int ipsec
  • SHUT_RD int no more receptions
  • SHUT_RDWR int no more receptions or transmissions
  • SHUT_WR int no more transmissions
  • SOCK_DGRAM int connectionless unreliable datagrams
  • SOCK_RAW int raw protocol interface
  • SOCK_STREAM int connection based byte stream
  • SOL_SOCKET int socket level
  • SOMAXCONN int maximum concurrent connections
  • SO_ACCEPTCONN int does this socket accept connections
  • SO_BINDTODEVICE int bind to a particular device
  • SO_BROADCAST int permit broadcasts
  • SO_DEBUG int turn-on socket debugging
  • SO_DONTROUTE int bypass standard routing
  • SO_ERROR int set socket error flag
  • SO_KEEPALIVE int periodically transmit keep-alive message
  • SO_LINGER int linger on a posix.unistd.close if data is still present
  • SO_OOBINLINE int leave out-of-band data inline
  • SO_RCVBUF int set receive buffer size
  • SO_RCVLOWAT int set receive buffer low water mark
  • SO_RCVTIMEO int set receive timeout
  • SO_REUSEADDR int reuse local addresses
  • SO_SNDBUF int set send buffer size
  • SO_SNDLOWAT int set send buffer low water mark
  • SO_SNDTIMEO int set send timeout
  • SO_TYPE int get the socket type
  • TCP_NODELAY int don't delay send for packet coalescing

Usage:

    -- Print socket constants supported on this host.
for name, value in pairs (require "posix.sys.socket") do
  if type (value) == "number" then
    print (name, value)
   end
end
generated by LDoc 1.5.0 Last updated 2025-02-16 13:16:41