recvmmsg()

Updated: May 06, 2022

Receive multiple messages and their headers from a socket

Synopsis:

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

int recvmmsg( int s,
              struct mmsghdr *mm,
              unsigned int vlen,
              unsigned int flags,
              struct timespec *to );

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_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, the function will return one. 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.
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

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