| 1 |
.\" Copyright 2011, Andi Kleen <[email protected]> |
| 2 |
.\" Copyright 2011, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.\" Syscall added in following commit |
| 8 |
.\" commit a2e2725541fad72416326798c2d7fa4dafb7d337 |
| 9 |
.\" Author: Arnaldo Carvalho de Melo <[email protected]> |
| 10 |
.\" Date: Mon Oct 12 23:40:10 2009 -0700 |
| 11 |
.\" |
| 12 |
.TH recvmmsg 2 2026-02-08 "Linux man-pages 6.18" |
| 13 |
.SH NAME |
| 14 |
recvmmsg \- receive multiple messages on a socket |
| 15 |
.SH LIBRARY |
| 16 |
Standard C library |
| 17 |
.RI ( libc ,\~ \-lc ) |
| 18 |
.SH SYNOPSIS |
| 19 |
.nf |
| 20 |
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| 21 |
.B #include <sys/socket.h> |
| 22 |
.P |
| 23 |
.BR "int recvmmsg(" "unsigned int n;" |
| 24 |
.BI " int " sockfd \ |
| 25 |
", struct mmsghdr " msgvec [ n "], unsigned int " n , |
| 26 |
.BI " int " flags ", struct timespec *" timeout ");" |
| 27 |
.fi |
| 28 |
.SH DESCRIPTION |
| 29 |
The |
| 30 |
.BR recvmmsg () |
| 31 |
system call is an extension of |
| 32 |
.BR recvmsg (2) |
| 33 |
that allows the caller to receive multiple messages from a socket |
| 34 |
using a single system call. |
| 35 |
(This has performance benefits for some applications.) |
| 36 |
A further extension over |
| 37 |
.BR recvmsg (2) |
| 38 |
is support for a timeout on the receive operation. |
| 39 |
.P |
| 40 |
The |
| 41 |
.I sockfd |
| 42 |
argument is the file descriptor of the socket to receive data from. |
| 43 |
.P |
| 44 |
The |
| 45 |
.I msgvec |
| 46 |
argument is a pointer to an array of |
| 47 |
.I mmsghdr |
| 48 |
structures. |
| 49 |
The size of this array is specified in |
| 50 |
.IR n . |
| 51 |
.P |
| 52 |
The |
| 53 |
.I mmsghdr |
| 54 |
structure is defined in |
| 55 |
.I <sys/socket.h> |
| 56 |
as: |
| 57 |
.P |
| 58 |
.in +4n |
| 59 |
.EX |
| 60 |
struct mmsghdr { |
| 61 |
struct msghdr msg_hdr; /* Message header */ |
| 62 |
unsigned int msg_len; /* Number of received bytes for header */ |
| 63 |
}; |
| 64 |
.EE |
| 65 |
.in |
| 66 |
.P |
| 67 |
The |
| 68 |
.I msg_hdr |
| 69 |
field is a |
| 70 |
.I msghdr |
| 71 |
structure, as described in |
| 72 |
.BR recvmsg (2). |
| 73 |
The |
| 74 |
.I msg_len |
| 75 |
field is the number of bytes returned for the message in the entry. |
| 76 |
This field has the same value as the return value of a single |
| 77 |
.BR recvmsg (2) |
| 78 |
on the header. |
| 79 |
.P |
| 80 |
The |
| 81 |
.I flags |
| 82 |
argument contains flags ORed together. |
| 83 |
The flags are the same as documented for |
| 84 |
.BR recvmsg (2), |
| 85 |
with the following addition: |
| 86 |
.TP |
| 87 |
.BR MSG_WAITFORONE " (since Linux 2.6.34)" |
| 88 |
Turns on |
| 89 |
.B MSG_DONTWAIT |
| 90 |
after the first message has been received. |
| 91 |
.P |
| 92 |
The |
| 93 |
.I timeout |
| 94 |
argument points to a |
| 95 |
.I struct timespec |
| 96 |
(see |
| 97 |
.BR clock_gettime (2)) |
| 98 |
defining a timeout (seconds plus nanoseconds) for the receive operation |
| 99 |
.RI ( "but see BUGS!" ). |
| 100 |
(This interval will be rounded up to the system clock granularity, |
| 101 |
and kernel scheduling delays mean that the blocking interval |
| 102 |
may overrun by a small amount.) |
| 103 |
If |
| 104 |
.I timeout |
| 105 |
is NULL, then the operation blocks indefinitely. |
| 106 |
.P |
| 107 |
A blocking |
| 108 |
.BR recvmmsg () |
| 109 |
call blocks until |
| 110 |
.I n |
| 111 |
messages have been received |
| 112 |
or until the timeout expires. |
| 113 |
A nonblocking call reads as many messages as are available |
| 114 |
(up to the limit specified by |
| 115 |
.IR n ) |
| 116 |
and returns immediately. |
| 117 |
.P |
| 118 |
On return from |
| 119 |
.BR recvmmsg (), |
| 120 |
successive elements of |
| 121 |
.I msgvec |
| 122 |
are updated to contain information about each received message: |
| 123 |
.I msg_len |
| 124 |
contains the size of the received message; |
| 125 |
the subfields of |
| 126 |
.I msg_hdr |
| 127 |
are updated as described in |
| 128 |
.BR recvmsg (2). |
| 129 |
The return value of the call indicates the number of elements of |
| 130 |
.I msgvec |
| 131 |
that have been updated. |
| 132 |
.SH RETURN VALUE |
| 133 |
On success, |
| 134 |
.BR recvmmsg () |
| 135 |
returns the number of messages received in |
| 136 |
.IR msgvec ; |
| 137 |
on error, \-1 is returned, and |
| 138 |
.I errno |
| 139 |
is set to indicate the error. |
| 140 |
.SH ERRORS |
| 141 |
Errors are as for |
| 142 |
.BR recvmsg (2). |
| 143 |
In addition, the following error can occur: |
| 144 |
.TP |
| 145 |
.B EINVAL |
| 146 |
.I timeout |
| 147 |
is invalid. |
| 148 |
.P |
| 149 |
See also BUGS. |
| 150 |
.SH STANDARDS |
| 151 |
Linux. |
| 152 |
.SH HISTORY |
| 153 |
Linux 2.6.33, |
| 154 |
glibc 2.12. |
| 155 |
.SH BUGS |
| 156 |
The |
| 157 |
.I timeout |
| 158 |
argument does not work as intended. |
| 159 |
.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=75371 |
| 160 |
.\" http://thread.gmane.org/gmane.linux.man/5677 |
| 161 |
The timeout is checked only after the receipt of each datagram, |
| 162 |
so that if up to |
| 163 |
.I n\-1 |
| 164 |
datagrams are received before the timeout expires, |
| 165 |
but then no further datagrams are received, the call will block forever. |
| 166 |
.P |
| 167 |
If an error occurs after at least one message has been received, |
| 168 |
the call succeeds, and returns the number of messages received. |
| 169 |
The error code is expected to be returned on a subsequent call to |
| 170 |
.BR recvmmsg (). |
| 171 |
In the current implementation, however, the error code can be overwritten |
| 172 |
in the meantime by an unrelated network event on a socket, |
| 173 |
for example an incoming ICMP packet. |
| 174 |
.SH EXAMPLES |
| 175 |
The following program uses |
| 176 |
.BR recvmmsg () |
| 177 |
to receive multiple messages on a socket and stores |
| 178 |
them in multiple buffers. |
| 179 |
The call returns if all buffers are filled or if the |
| 180 |
timeout specified has expired. |
| 181 |
.P |
| 182 |
The following snippet periodically generates UDP datagrams |
| 183 |
containing a random number: |
| 184 |
.P |
| 185 |
.in +4n |
| 186 |
.EX |
| 187 |
.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;" |
| 188 |
.B " sleep 0.25; done" |
| 189 |
.EE |
| 190 |
.in |
| 191 |
.P |
| 192 |
These datagrams are read by the example application, which |
| 193 |
can give the following output: |
| 194 |
.P |
| 195 |
.in +4n |
| 196 |
.EX |
| 197 |
.RB "$" " ./a.out" |
| 198 |
5 messages received |
| 199 |
1 11782 |
| 200 |
2 11345 |
| 201 |
3 304 |
| 202 |
4 13514 |
| 203 |
5 28421 |
| 204 |
.EE |
| 205 |
.in |
| 206 |
.SS Program source |
| 207 |
\& |
| 208 |
.\" SRC BEGIN (recvmmsg.c) |
| 209 |
.EX |
| 210 |
#define _GNU_SOURCE |
| 211 |
#include <arpa/inet.h> |
| 212 |
#include <netinet/in.h> |
| 213 |
#include <stdio.h> |
| 214 |
#include <stdlib.h> |
| 215 |
#include <string.h> |
| 216 |
#include <sys/socket.h> |
| 217 |
#include <time.h> |
| 218 |
\& |
| 219 |
int |
| 220 |
main(void) |
| 221 |
{ |
| 222 |
#define VLEN 10 |
| 223 |
#define BUFSIZE 200 |
| 224 |
#define TIMEOUT 1 |
| 225 |
int sockfd, retval; |
| 226 |
char bufs[VLEN][BUFSIZE+1]; |
| 227 |
struct iovec iovecs[VLEN]; |
| 228 |
struct mmsghdr msgs[VLEN]; |
| 229 |
struct timespec timeout; |
| 230 |
struct sockaddr_in addr; |
| 231 |
\& |
| 232 |
sockfd = socket(AF_INET, SOCK_DGRAM, 0); |
| 233 |
if (sockfd == \-1) { |
| 234 |
perror("socket()"); |
| 235 |
exit(EXIT_FAILURE); |
| 236 |
} |
| 237 |
\& |
| 238 |
addr.sin_family = AF_INET; |
| 239 |
addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK); |
| 240 |
addr.sin_port = htons(1234); |
| 241 |
if (bind(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { |
| 242 |
perror("bind()"); |
| 243 |
exit(EXIT_FAILURE); |
| 244 |
} |
| 245 |
\& |
| 246 |
memset(msgs, 0, sizeof(msgs)); |
| 247 |
for (size_t i = 0; i < VLEN; i++) { |
| 248 |
iovecs[i].iov_base = bufs[i]; |
| 249 |
iovecs[i].iov_len = BUFSIZE; |
| 250 |
msgs[i].msg_hdr.msg_iov = &iovecs[i]; |
| 251 |
msgs[i].msg_hdr.msg_iovlen = 1; |
| 252 |
} |
| 253 |
\& |
| 254 |
timeout.tv_sec = TIMEOUT; |
| 255 |
timeout.tv_nsec = 0; |
| 256 |
\& |
| 257 |
retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout); |
| 258 |
if (retval == \-1) { |
| 259 |
perror("recvmmsg()"); |
| 260 |
exit(EXIT_FAILURE); |
| 261 |
} |
| 262 |
\& |
| 263 |
printf("%d messages received\[rs]n", retval); |
| 264 |
for (size_t i = 0; i < retval; i++) { |
| 265 |
bufs[i][msgs[i].msg_len] = 0; |
| 266 |
printf("%zu %s", i+1, bufs[i]); |
| 267 |
} |
| 268 |
exit(EXIT_SUCCESS); |
| 269 |
} |
| 270 |
.EE |
| 271 |
.\" SRC END |
| 272 |
.SH SEE ALSO |
| 273 |
.BR clock_gettime (2), |
| 274 |
.BR recvmsg (2), |
| 275 |
.BR sendmmsg (2), |
| 276 |
.BR sendmsg (2), |
| 277 |
.BR socket (2), |
| 278 |
.BR socket (7) |