# Object Instance `nixio.Socket`

Socket Object. Supports IPv4, IPv6 and UNIX (POSIX only) families.

## Functions

Socket:accept () | Accept a connection on the socket.
Socket:bind (host, port) | Bind the socket to a network address.
Socket:close () | Close the socket.
Socket:connect (host, port) | Connect the socket to a network address.
Socket:fileno () | Get the number of the filedescriptor.
Socket:getopt (level, option) | Get a socket option.
Socket:getpeername () | Get the peer address of a socket.
Socket:getsockname () | Get the local address of a socket.
Socket:listen (backlog) | Listen for connections on the socket.
Socket:read (length) | Receive a message on the socket (This is an alias for recv).
Socket:recv (length) | Receive a message on the socket.
Socket:recvfrom (length) | Receive a message on the socket including the senders source address.
Socket:send (buffer, offset, length) | Send a message on the socket.
Socket:sendto (buffer, host, port, offset, length) | Send a message on the socket specifying the destination.
Socket:setblocking (blocking) | Set the blocking mode of the socket.
Socket:setopt (level, option, value) | Set a socket option.
Socket:shutdown (how) | Shut down part of a full-duplex connection.
Socket:write (buffer, offset, length) | Send a message on the socket (This is an alias for send).

## Functions

Socket:accept ()
  Accept a connection on the socket.

  ### Return values:

  1. Socket Object
  2. Peer IP-Address
  3. Peer Port
Socket:bind (host, port)
  Bind the socket to a network address.

  ### Parameters

  - host: Host (optional, default: all addresses)
  - port: Port or service description

  ### Usage

  - This function calls getaddrinfo() and bind() but NOT listen().
  - If host is a domain name it will be looked up and bind() tries the IP-Addresses in the order returned by the DNS resolver until the bind succeeds.
  - UNIX sockets ignore the port, and interpret host as a socket path.

  ### Return value:

  true
Socket:close ()
  Close the socket.

  ### Return value:

  true
Socket:connect (host, port)
  Connect the socket to a network address.

  ### Parameters

  - host: Hostname or IP-Address (optional, default: localhost)
  - port: Port or service description

  ### Usage

  - This function calls getaddrinfo() and connect().
  - If host is a domain name it will be looked up and connect() tries the IP-Addresses in the order returned by the DNS resolver until the connect succeeds.
  - UNIX sockets ignore the port, and interpret host as a socket path.

  ### Return value:

  true
Socket:fileno ()
  Get the number of the filedescriptor.

  ### Return value:

  file descriptor number
Socket:getopt (level, option)
  Get a socket option.

  ### Parameters

  - level: Level ["socket", "tcp", "ip", "ipv6"]
  - option: Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf", "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute", "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP), "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop" (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops" (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)]

  ### Return value:

  Value
Socket:getpeername ()
  Get the peer address of a socket.

  ### Return values:

  1. IP-Address
  2. Port
Socket:getsockname ()
  Get the local address of a socket.

  ### Return values:

  1. IP-Address
  2. Port
Socket:listen (backlog)
  Listen for connections on the socket.

  ### Parameters

  - backlog: Length of queue for pending connections

  ### Return value:

  true
Socket:read (length)
  Receive a message on the socket (This is an alias for recv). See the recvfrom description for more details.

  ### Parameters

  - length: Amount of data to read (in Bytes).

  ### Return value:

  buffer containing data successfully read

  ### See also:

  - Socket:recvfrom
Socket:recv (length)
  Receive a message on the socket. This function is identical to recvfrom except that it does not return the sender's source address. See the recvfrom description for more details.

  ### Parameters

  - length: Amount of data to read (in Bytes).

  ### Return value:

  buffer containing data successfully read

  ### See also:

  - Socket:recvfrom
Socket:recvfrom (length)
  Receive a message on the socket including the senders source address.

  ### Parameters

  - length: Amount of data to read (in Bytes).

  ### Usage

  - Warning: It is not guaranteed that all requested data is read at once. You have to check the return value - the length of the buffer actually read - or use the safe IO functions in the high-level IO utility module.
  - The length of the return buffer is limited by the (compile time) nixio buffersize which is nixio.const.buffersize (8192 by default). Any read request greater than that will be safely truncated to this value.

  ### Return values:

  1. buffer containing data successfully read
  2. host IP-Address of the sender
  3. port Port of the sender
Socket:send (buffer, offset, length)
  Send a message on the socket. This function is identical to sendto except for the missing destination parameters. See the sendto description for a detailed description.

  ### Parameters

  - buffer: Buffer holding the data to be written.
  - offset: Offset to start reading the buffer from. (optional)
  - length: Length of chunk to read from the buffer. (optional)

  ### Return value:

  number of bytes written

  ### See also:

  - Socket:sendto
Socket:sendto (buffer, host, port, offset, length)
  Send a message on the socket specifying the destination.

  ### Parameters

  - buffer: Buffer holding the data to be written.
  - host: Target IP-Address
  - port: Target Port
  - offset: Offset to start reading the buffer from. (optional)
  - length: Length of chunk to read from the buffer. (optional)

  ### Usage

  - Warning: It is not guaranteed that all data in the buffer is written at once. You have to check the return value - the number of bytes actually written - or use the safe IO functions in the high-level IO utility module.
  - Unlike standard Lua indexing the lowest offset and default is 0.

  ### Return value:

  number of bytes written
Socket:setblocking (blocking)
  Set the blocking mode of the socket.

  ### Parameters

  - blocking: (boolean)

  ### Return value:

  true
Socket:setopt (level, option, value)
  Set a socket option.

  ### Parameters

  - level: Level ["socket", "tcp", "ip", "ipv6"]
  - option: Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf", "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute", "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP), "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop" (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops" (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)]
  - value: Value

  ### Return value:

  true
Socket:shutdown (how)
  Shut down part of a full-duplex connection.

  ### Parameters

  - how: (optional, default: rdwr) ["rdwr", "rd", "wr"]

  ### Return value:

  true
Socket:write (buffer, offset, length)
  Send a message on the socket (This is an alias for send). See the sendto description for a detailed description.

  ### Parameters

  - buffer: Buffer holding the data to be written.
  - offset: Offset to start reading the buffer from. (optional)
  - length: Length of chunk to read from the buffer. (optional)

  ### Return value:

  number of bytes written

  ### See also:

  - Socket:sendto