Updated: October 26, 2022

Receive a message and its header from a socket


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

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


The descriptor for the socket; see socket().
A pointer to a msghdr structure where the function can store the message header; see below.
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.



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


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:

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


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


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


POSIX 1003.1

Cancellation point Yes
Interrupt handler No
Signal handler No
Thread Yes