recvmsg()

#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_DONTWAIT — if no data is available, then instead of blocking, return immediately with the error EAGAIN.
• MSG_NOTIFICATION — if the flag is not set, then the function returns data. If a notification has arrived, then the flag is set and it returns a notification in the msg_iov field.
• 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.
• MSG_WAITFORONE — wait for one packet or an error. This flag causes the operation to block until at least one packet is available. With this setting, you can receive as many as vlen packets, but if only one is available, then the function returns one. However, the call may return less data than available under the following scenarios:
  • a signal is caught
  • an error or disconnect occurs
  • the incoming packet is a different data type from the one previously received
  This flag turns on MSG_DONTWAIT after the first message has been received.

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