]>
Commit | Line | Data |
---|---|---|
946fb6e2 | 1 | .\" Copyright (C) 2011 by Andi Kleen <andi@firstfloor.org> |
8b0ea18b | 2 | .\" and Copyright (c) 2011 by Michael Kerrisk <mtk.manpages@gmail.com> |
946fb6e2 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
946fb6e2 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
946fb6e2 | 25 | .\" |
6d2f6aff MK |
26 | .\" Syscall added in following commit |
27 | .\" commit a2e2725541fad72416326798c2d7fa4dafb7d337 | |
28 | .\" Author: Arnaldo Carvalho de Melo <acme@redhat.com> | |
29 | .\" Date: Mon Oct 12 23:40:10 2009 -0700 | |
30 | .\" | |
b8efb414 | 31 | .TH RECVMMSG 2 2016-10-08 "Linux" "Linux Programmer's Manual" |
242966fd AK |
32 | .SH NAME |
33 | recvmmsg \- receive multiple messages on a socket | |
34 | .SH SYNOPSIS | |
8b0ea18b | 35 | .nf |
ffed4546 | 36 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
242966fd | 37 | .BI "#include <sys/socket.h>" |
dbfe9c70 | 38 | .PP |
8b0ea18b | 39 | .BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \ |
242966fd AK |
40 | ", unsigned int " vlen "," |
41 | .br | |
c409c4ff | 42 | .BI " unsigned int " flags ", struct timespec *" timeout ");" |
8b0ea18b | 43 | .fi |
242966fd | 44 | .SH DESCRIPTION |
c409c4ff | 45 | The |
8b0ea18b MK |
46 | .BR recvmmsg () |
47 | system call is an extension of | |
48 | .BR recvmsg (2) | |
49 | that allows the caller to receive multiple messages from a socket | |
50 | using a single system call. | |
51 | (This has performance benefits for some applications.) | |
52 | A further extension over | |
53 | .BR recvmsg (2) | |
54 | is support for a timeout on the receive operation. | |
efeece04 | 55 | .PP |
8b0ea18b | 56 | The |
c409c4ff | 57 | .I sockfd |
8b0ea18b | 58 | argument is the file descriptor of the socket to receive data from. |
efeece04 | 59 | .PP |
8b0ea18b MK |
60 | The |
61 | .I msgvec | |
62 | argument is a pointer to an array of | |
242966fd | 63 | .I mmsghdr |
8b0ea18b MK |
64 | structures. |
65 | The size of this array is specified in | |
66 | .IR vlen . | |
efeece04 | 67 | .PP |
8b0ea18b MK |
68 | The |
69 | .I mmsghdr | |
70 | structure is defined in | |
71 | .I <sys/socket.h> | |
242966fd | 72 | as: |
efeece04 | 73 | .PP |
242966fd AK |
74 | .in +4n |
75 | .nf | |
76 | struct mmsghdr { | |
77 | struct msghdr msg_hdr; /* Message header */ | |
78 | unsigned int msg_len; /* Number of received bytes for header */ | |
79 | }; | |
80 | .fi | |
81 | .in | |
82 | .PP | |
8b0ea18b | 83 | The |
c409c4ff | 84 | .I msg_hdr |
8b0ea18b | 85 | field is a |
242966fd | 86 | .I msghdr |
8b0ea18b MK |
87 | structure, as described in |
88 | .BR recvmsg (2). | |
89 | The | |
90 | .I msg_len | |
91 | field is the number of bytes returned for the message in the entry. | |
242966fd | 92 | This field has the same value as the return value of a single |
8b0ea18b | 93 | .BR recvmsg (2) |
242966fd | 94 | on the header. |
efeece04 | 95 | .PP |
8b0ea18b MK |
96 | The |
97 | .I flags | |
98 | argument contains flags ORed together. | |
99 | The flags are the same as documented for | |
100 | .BR recvmsg (2), | |
101 | with the following addition: | |
102 | .TP | |
bbb9456e | 103 | .BR MSG_WAITFORONE " (since Linux 2.6.34)" |
8b0ea18b MK |
104 | Turns on |
105 | .B MSG_DONTWAIT | |
242966fd | 106 | after the first message has been received. |
8b0ea18b MK |
107 | .PP |
108 | The | |
109 | .I timeout | |
c409c4ff | 110 | argument points to a |
242966fd | 111 | .I struct timespec |
c409c4ff | 112 | (see |
8b0ea18b | 113 | .BR clock_gettime (2)) |
dfc00363 MK |
114 | defining a timeout (seconds plus nanoseconds) for the receive operation |
115 | .RI ( "but see BUGS!" ). | |
3a1876bd MK |
116 | (This interval will be rounded up to the system clock granularity, |
117 | and kernel scheduling delays mean that the blocking interval | |
118 | may overrun by a small amount.) | |
8b0ea18b MK |
119 | If |
120 | .I timeout | |
ae7319ae | 121 | is NULL, then the operation blocks indefinitely. |
efeece04 | 122 | .PP |
8b0ea18b MK |
123 | A blocking |
124 | .BR recvmmsg () | |
125 | call blocks until | |
126 | .I vlen | |
127 | messages have been received | |
128 | or until the timeout expires. | |
129 | A nonblocking call reads as many messages as are available | |
130 | (up to the limit specified by | |
131 | .IR vlen ) | |
132 | and returns immediately. | |
efeece04 | 133 | .PP |
8b0ea18b MK |
134 | On return from |
135 | .BR recvmmsg (), | |
136 | successive elements of | |
137 | .IR msgvec | |
138 | are updated to contain information about each received message: | |
139 | .I msg_len | |
140 | contains the size of the received message; | |
141 | the subfields of | |
142 | .I msg_hdr | |
c409c4ff | 143 | are updated as described in |
8b0ea18b MK |
144 | .BR recvmsg (2). |
145 | The return value of the call indicates the number of elements of | |
146 | .I msgvec | |
147 | that have been updated. | |
242966fd | 148 | .SH RETURN VALUE |
8b0ea18b MK |
149 | On success, |
150 | .BR recvmmsg () | |
242966fd | 151 | returns the number of messages received in |
8b0ea18b MK |
152 | .IR msgvec ; |
153 | on error, \-1 is returned, and | |
154 | .I errno | |
155 | is set to indicate the error. | |
156 | .SH ERRORS | |
157 | Errors are as for | |
158 | .BR recvmsg (2). | |
159 | In addition, the following error can occur: | |
160 | .TP | |
161 | .B EINVAL | |
162 | .I timeout | |
163 | is invalid. | |
242966fd AK |
164 | .SH VERSIONS |
165 | The | |
8b0ea18b | 166 | .BR recvmmsg () |
bbb9456e | 167 | system call was added in Linux 2.6.33. |
8b0ea18b MK |
168 | Support in glibc was added in version 2.12. |
169 | .SH CONFORMING TO | |
170 | .BR recvmmsg () | |
171 | is Linux-specific. | |
41932d34 MK |
172 | .SH BUGS |
173 | The | |
174 | .I timeout | |
175 | argument does not work as intended. | |
176 | .\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=75371 | |
177 | .\" http://thread.gmane.org/gmane.linux.man/5677 | |
178 | The timeout is checked only after the receipt of each datagram, | |
179 | so that if up to | |
180 | .I vlen\-1 | |
181 | datagrams are received before the timeout expires, | |
182 | but then no further datagrams are received, the call will block forever. | |
f2246260 EDB |
183 | .SH EXAMPLE |
184 | .PP | |
9f1b9726 MK |
185 | The following program uses |
186 | .BR recvmmsg () | |
f2246260 | 187 | to receive multiple messages on a socket and stores |
9f1b9726 MK |
188 | them in multiple buffers. |
189 | The call returns if all buffers are filled or if the | |
2c208a7a | 190 | timeout specified has expired. |
efeece04 | 191 | .PP |
9f1b9726 | 192 | The following snippet periodically generates UDP datagrams |
f2246260 | 193 | containing a random number: |
e646a1ba | 194 | .PP |
f2246260 | 195 | .in +4n |
e646a1ba | 196 | .EX |
2c208a7a MK |
197 | .RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234; " |
198 | .B " sleep 0.25; done" | |
f2246260 EDB |
199 | .fi |
200 | .in | |
efeece04 | 201 | .PP |
9f1b9726 | 202 | These datagrams are read by the example application, which |
f2246260 | 203 | can give the following output: |
e646a1ba | 204 | .PP |
f2246260 | 205 | .in +4n |
e646a1ba | 206 | .EX |
f2246260 EDB |
207 | .RB "$" " ./a.out" |
208 | 5 messages received | |
209 | 1 11782 | |
210 | 2 11345 | |
211 | 3 304 | |
212 | 4 13514 | |
213 | 5 28421 | |
214 | .fi | |
215 | .in | |
216 | .SS Program source | |
217 | \& | |
e7d0bb47 | 218 | .EX |
f2246260 | 219 | #define _GNU_SOURCE |
9f1b9726 | 220 | #include <netinet/ip.h> |
f2246260 EDB |
221 | #include <stdio.h> |
222 | #include <stdlib.h> | |
223 | #include <string.h> | |
224 | #include <sys/socket.h> | |
225 | ||
9f1b9726 | 226 | int |
2c208a7a | 227 | main(void) |
f2246260 EDB |
228 | { |
229 | #define VLEN 10 | |
9f1b9726 | 230 | #define BUFSIZE 200 |
f2246260 EDB |
231 | #define TIMEOUT 1 |
232 | int sockfd, retval, i; | |
24a31d63 | 233 | struct sockaddr_in addr; |
f2246260 EDB |
234 | struct mmsghdr msgs[VLEN]; |
235 | struct iovec iovecs[VLEN]; | |
236 | char bufs[VLEN][BUFSIZE+1]; | |
237 | struct timespec timeout; | |
238 | ||
239 | sockfd = socket(AF_INET, SOCK_DGRAM, 0); | |
240 | if (sockfd == \-1) { | |
241 | perror("socket()"); | |
242 | exit(EXIT_FAILURE); | |
243 | } | |
244 | ||
24a31d63 MK |
245 | addr.sin_family = AF_INET; |
246 | addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK); | |
247 | addr.sin_port = htons(1234); | |
248 | if (bind(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { | |
f2246260 EDB |
249 | perror("bind()"); |
250 | exit(EXIT_FAILURE); | |
251 | } | |
252 | ||
253 | memset(msgs, 0, sizeof(msgs)); | |
254 | for (i = 0; i < VLEN; i++) { | |
255 | iovecs[i].iov_base = bufs[i]; | |
256 | iovecs[i].iov_len = BUFSIZE; | |
257 | msgs[i].msg_hdr.msg_iov = &iovecs[i]; | |
258 | msgs[i].msg_hdr.msg_iovlen = 1; | |
259 | } | |
260 | ||
261 | timeout.tv_sec = TIMEOUT; | |
262 | timeout.tv_nsec = 0; | |
263 | ||
264 | retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout); | |
265 | if (retval == \-1) { | |
266 | perror("recvmmsg()"); | |
267 | exit(EXIT_FAILURE); | |
268 | } | |
269 | ||
270 | printf("%d messages received\\n", retval); | |
271 | for (i = 0; i < retval; i++) { | |
272 | bufs[i][msgs[i].msg_len] = 0; | |
273 | printf("%d %s", i+1, bufs[i]); | |
274 | } | |
275 | exit(EXIT_SUCCESS); | |
276 | } | |
e7d0bb47 | 277 | .EE |
8b0ea18b MK |
278 | .SH SEE ALSO |
279 | .BR clock_gettime (2), | |
280 | .BR recvmsg (2), | |
6df34945 | 281 | .BR sendmmsg (2), |
8b0ea18b MK |
282 | .BR sendmsg (2), |
283 | .BR socket (2), | |
284 | .BR socket (7) |