recvmmsg()

Arguments:

s

The descriptor for the socket; see socket().

mm

A pointer to an array of mmsghdr structures where the function can store the message headers; see below.

vlen

The length of the mm array; limited to 1024 elements.

flags

A bitwise OR of zero or more of the following:

• 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 the full request or an 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.

to

The length of time to wait for messages to be received, after which recvmmsg() returns. Setting this value to NULL disables the timeout.

This is strictly an input parameter, because the function doesn't update the timespec fields, even if it returns sooner than the timeout period.

Library:

libsocket

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

Description:

The recvmmsg() function receives multiple messages from a socket, s, whether or not it's connection-oriented.

The recvmmsg() function uses a mmsghdr structure to minimize the number of directly supplied parameters. This structure is defined in <sys/socket.h> as follows:

struct mmsghdr {
    struct msghdr   msg_hdr; /* the message to be sent */
    unsigned int    msg_len; /* number of bytes transmitted */
};

The msg_len member contains the number of bytes sent for each msg_hdr member. The array has vlen elements, but if there's an error, a number fewer than vlen may be returned. For a description of the msghdr structure, see recvmsg().

Returns:

The number of messages 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:

Unix