recvmsg(3)

NAME
recvmsg - receive a message on a socket

SYNOPSIS
#include <sys/socket.h>

int recvmsg(int s, struct msghdr *msg, int flags);

DESCRIPTION
recvmsg is used to receive a message from another socket. s is a socket descriptor that specifies the socket on which the message will be received. msg points to an object of type struct msghdr into which the received message will be placed. struct msghdr is explained below.

recvmsg operates the same way as recvfrom, except that it is able to scatter the data into the msg_iov member of struct msghdr. Note that receiving of access rights is not implemented. Do not rely on this behavior, because it might change in the future.

struct msghdr is defined in <sys/socket.h>, and has the following form :

    struct msghdr {
    	void	*msg_name;	/* optional address */
    	size_t	msg_namelen;	/* size of address  */
    	struct iovec *msg_iov;	/* scatter array for data */
    	size_t	msg_iovlen;	/* # of elements in msg_iov */
    	void    *msg_accrights;	/* access rights */
    	size_t	msg_accrightslen; /* size of msg_accrights */
    }

msg_name contains the source address of the message; msg_name may be a null pointer if you are not interested in this information. msg_iov is the location of the scatter data. msg_accrights specifies a buffer to receive any access rights along with the message. Transfer of access rights is not implemented, so you should set the msg_acccrights field to NULL indicating that access rights are not being transferred.

See recvfrom(3) to learn more about the behavior of recvmsg.

RETURN VALUE
If the recvmsg call is successful, it returns the number of bytes received. If the call fails, -1 is returned and an error code is stored in errno.

DIAGNOSTICS
The call to recvmsg fail if:

    [EBADF]
        The argument s is an invalid descriptor.

    [EINVAL]
        The argument s is not a socket. The msg parameter contains invalid members.

    [ENOMEM]
        There is insufficient buffer space to send the message.

    [EINTR]
        The receive was interrupted by delivery of a signal before any data was available for the receive.

    [ENOTCONN]
        Receive on a SOCK_STREAM socket that is not yet connected.

    [EOPNOTSUPP]
        The MSG_OOB or MSG_PEEK flag was set for any AF_UNIX socket. Neither MSG_PEEK nor MSG_OOB is supported for AF_UNIX sockets.

SEE ALSO
getsockopt(3), select(3), recv(3), recvfrom(3), socket(3).