recvmsg

        # BasicSocket.recvmsg

(from ruby core)
---
    basicsocket.recvmsg(maxmesglen=nil, flags=0, maxcontrollen=nil, opts={}) => [mesg, sender_addrinfo, rflags, *controls]

---

recvmsg receives a message using recvmsg(2) system call in blocking
manner.

*maxmesglen* is the maximum length of mesg to receive.

*flags* is bitwise OR of MSG_* constants such as Socket::MSG_PEEK.

*maxcontrollen* is the maximum length of controls (ancillary data) to
receive.

*opts* is option hash. Currently :scm_rights=>bool is the only option.

:scm_rights option specifies that application expects SCM_RIGHTS control
message. If the value is nil or false, application don't expects
SCM_RIGHTS control message. In this case, recvmsg closes the passed file
descriptors immediately. This is the default behavior.

If :scm_rights value is neither nil nor false, application expects
SCM_RIGHTS control message. In this case, recvmsg creates IO objects for
each file descriptors for Socket::AncillaryData#unix_rights method.

The return value is 4-elements array.

*mesg* is a string of the received message.

*sender_addrinfo* is a sender socket address for connection-less socket.
It is an Addrinfo object. For connection-oriented socket such as TCP,
sender_addrinfo is platform dependent.

*rflags* is a flags on the received message which is bitwise OR of MSG_*
constants such as Socket::MSG_TRUNC. It will be nil if the system uses
4.3BSD style old recvmsg system call.

*controls* is ancillary data which is an array of Socket::AncillaryData
objects such as:

    #<Socket::AncillaryData: AF_UNIX SOCKET RIGHTS 7>

*maxmesglen* and *maxcontrollen* can be nil. In that case, the buffer
will be grown until the message is not truncated. Internally, MSG_PEEK
is used. Buffer full and MSG_CTRUNC are checked for truncation.

recvmsg can be used to implement recv_io as follows:

    mesg, sender_sockaddr, rflags, *controls = sock.recvmsg(:scm_rights=>true)
    controls.each {|ancdata|
      if ancdata.cmsg_is?(:SOCKET, :RIGHTS)
        return ancdata.unix_rights[0]
      end
    }