Document new socket functions

Product: Tarantool
Since: 3.0
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/socket/
SME: @ locker

Details

Two socket module functions and one socket object method were added to
Tarantool 3.0:

• socket.from_fd(fd): constructs a socket object from the file
  descriptor number. Returns the new socket object on success. Never
  fails. Note, the function doesn't perform any checks on the given
  file descriptor so technically it's possible to pass a closed file
  descriptor or a file descriptor that refers to a file, in which case
  the new socket object methods may not work as expected.

• socket:detach(): like socket:close() but doesn't close the socket
  file descriptor, only switches the socket object to the closed state.
  Returns nothing. If the socket was already detached or closed, raises
  an exception.

  Along with socket.from_fd, this method may be used for transferring
  file descriptor ownership from one socket to another:

  local socket = require('socket')
  local s1 = socket('AF_INET', 'SOCK_STREAM', 'tcp')
  local s2 = socket.from_fd(s1:fd())
  s1:detach()
  

• socket.socketpair(domain, type, proto): a wrapper around the
  socketpair system call. Returns two socket objects representing
  the two ends of the new socket pair on success. On failure, returns
  nil and sets errno.

  Example:

  local errno = require('errno')
  local socket = require('socket')
  local s1, s1 = socket.socketpair('AF_UNIX', 'SOCK_STREAM', 0)
  if not s1 then
      error('socketpair: ' .. errno.strerror())
  end
  s1:send('foo')
  assert(s2:recv() == 'foo')
  s1:close()
  s2:close()
  

Requested by @locker in https://github.com/tarantool/tarantool/commit/61130805b15c506657818606f3a85a3b2b32311d.

Definition of done

• socket.from_fd(fd) module function
• socket:detach()module function
• socket.socketpair(domain, type, proto) object method

Start with the socket module root document at the linked reference page and locate its function and method entries. Document socket.from_fd(fd), socket:detach(), and socket.socketpair(domain, type, proto), including the behavior and examples given in the issue; done means all three Definition of done items are covered.