# 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:

  accept(2)
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:

  bind(2)
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:

  connect(2)
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:

  getaddrinfo(2)

  ### 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:

  getpeername(2)

  ### 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:

  getsockname(2)

  ### 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:

  getsockopt(2)

  ### 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:

  if_nametoindex(3)

  ### 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:

  listen(2)
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:

  recv(2)
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:

  recvfrom(2)
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:

  send(2)
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:

  sendto(2)
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:

  setsockopt(2)

  ### 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:

  shutdown(2)

  ### 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:

  socket(2)

  ### 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:

  socketpair(2)

  ### 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