Debian Codegraph @

upstream/debian-trixie/man2/recvmmsg.2

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