recvmsg()

Updated: May 06, 2022

Receive a message and its header from a socket

Synopsis:

#include <sys/types.h>
#include <sys/socket.h>

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

Arguments:

s
The descriptor for the socket; see socket().
msg
A pointer to a msghdr structure where the function can store the message header; see below.
flags
A combination formed by ORing one or more of the values:
  • MSG_OOB — process out-of-band data. This flag requests receipt of out-of-band data that wouldn't be received in the normal data stream. You can't use this flag with protocols that place expedited data at the head of the normal data queue.
  • MSG_PEEK — peek at the incoming message. This flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data.
  • MSG_WAITALL — wait for full request or error. This flag requests that the operation block until the full request is satisfied. But the call may still return less data than requested if a signal is caught, if an error or disconnect occurs, or if the next data to be received is of a different type than that returned.

Library:

libsocket

Use the -l socket option to qcc to link against this library.

Description:

The recvmsg() routine receives a message from a socket, s, whether or not it's connection-oriented.

The recvmsg() call uses a msghdr structure to minimize the number of directly supplied parameters. This structure, defined in <sys/socket.h>, has the following form:

struct msghdr {
        void            *msg_name;      /* optional address */
        socklen_t       msg_namelen;    /* size of address */
        struct iovec    *msg_iov;       /* scatter/gather array */
        int             msg_iovlen;     /* # elements in msg_iov */
        void            *msg_control;   /* ancillary data, see below */
        socklen_t       msg_controllen; /* ancillary data buffer len */
        int             msg_flags;      /* flags on received message */
};

The msg_name and msg_namelen parameters specify the address (source address for recvmsg(); destination address for sendmsg()) if the socket is unconnected; the msg_name parameter may be given as a null pointer if no names are desired or required.

The msg_iov and msg_iovlen parameters describe scatter-gather locations, as discussed in read().

The msg_control parameter, whose length is determined by msg_controllen, points to a buffer for other protocol-control related messages or for other miscellaneous ancillary data. The messages are of the form:

struct cmsghdr {
        socklen_t       cmsg_len;       /* data byte count, including hdr */
        int             cmsg_level;     /* originating protocol */
        int             cmsg_type;      /* protocol-specific type */
        /* followed by  unsigned char  cmsg_data[]; */
};

With recvmsg() and recvmmsg(), the length in msg_controllen must not exceed SSIZE_MAX (see <limits.h>), or the function fails and sets errno to EOVERFLOW. With sendmsg() or sendmmsg(), msg_controllen must not exceed SSIZE_MAX - sizeof(_io_sock_sendto) - sizeof(socklen_t), or EOVERFLOW occurs.

The msg_flags field is set on return according to the message received:

MSG_CTRUNC
Indicates that some control data was discarded due to lack of space in the buffer for ancillary data.
MSG_EOR
Indicates end-of-record; the data returned completed a record.
MSG_OOB
Indicates that expedited or out-of-band data was received.
MSG_TRUNC
Indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied.

Returns:

The number of bytes received, or -1 if an error occurs (errno is set).

Errors:

ENOMEM
Not enough memory.
EOVERFLOW
An attempt was made to receive an amount of data that exceeds the allowable limit.

Classification:

POSIX 1003.1

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler No
Thread Yes