SYNOPSIS

DESCRIPTION

The
recvmmsg()
system call is an extension of
recvmsg(2)
that allows the caller to receive multiple messages from a socket
using a single system call.
(This has performance benefits for some applications.)
A further extension over
recvmsg(2)
is support for a timeout on the receive operation.

The
sockfd
argument is the file descriptor of the socket to receive data from.

The
msgvec
argument is a pointer to an array of
mmsghdr
structures.
The size of this array is specified in
vlen.

The
msg_hdr
field is a
msghdr
structure, as described in
recvmsg(2).
The
msg_len
field is the number of bytes returned for the message in the entry.
This field has the same value as the return value of a single
recvmsg(2)
on the header.

The
flags
argument contains flags ORed together.
The flags are the same as documented for
recvmsg(2),
with the following addition:

MSG_WAITFORONE (since Linux 2.6.34)

Turns on
MSG_DONTWAIT
after the first message has been received.

The
timeout
argument points to a
struct timespec
(see
clock_gettime(2))
defining a timeout (seconds plus nanoseconds) for the receive operation
(but see BUGS!).
(This interval will be rounded up to the system clock granularity,
and kernel scheduling delays mean that the blocking interval
may overrun by a small amount.)
If
timeout
is NULL, then the operation blocks indefinitely.

A blocking
recvmmsg()
call blocks until
vlen
messages have been received
or until the timeout expires.
A nonblocking call reads as many messages as are available
(up to the limit specified by
vlen)
and returns immediately.

On return from
recvmmsg(),
successive elements of
msgvec
are updated to contain information about each received message:
msg_len
contains the size of the received message;
the subfields of
msg_hdr
are updated as described in
recvmsg(2).
The return value of the call indicates the number of elements of
msgvec
that have been updated.

RETURN VALUE

On success,
recvmmsg()
returns the number of messages received in
msgvec;
on error, -1 is returned, and
errno
is set to indicate the error.

ERRORS

Errors are as for
recvmsg(2).
In addition, the following error can occur:

EINVAL

timeout
is invalid.

VERSIONS

The
recvmmsg()
system call was added in Linux 2.6.33.
Support in glibc was added in version 2.12.

CONFORMING TO

recvmmsg()
is Linux-specific.

BUGS

The
timeout
argument does not work as intended.
The timeout is checked only after the receipt of each datagram,
so that if up to
vlen-1
datagrams are received before the timeout expires,
but then no further datagrams are received, the call will block forever.

EXAMPLE

The following program uses
recvmmsg()
to receive multiple messages on a socket and stores
them in multiple buffers.
The call returns if all buffers are filled or if the
timeout specified has expired.

SEE ALSO

COLOPHON

This page is part of release 4.13 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
https://www.kernel.org/doc/man-pages/.