1RECVMMSG(2) Linux Programmer's Manual RECVMMSG(2)
2
6 recvmmsg - receive multiple messages on a socket
7
9 #define _GNU_SOURCE
10 #include <sys/socket.h>
11 int recvmmsg(int sockfd, struct mmsghdr *msgvec, unsigned int vlen,
13 unsigned int flags, struct timespec *timeout);
14
16 The recvmmsg() system call is an extension of recvmsg(2) that allows
17 the caller to receive multiple messages from a socket using a single
18 system call. (This has performance benefits for some applications.) A
19 further extension over recvmsg(2) is support for a timeout on the
20 receive operation.
21 The sockfd argument is the file descriptor of the socket to receive
23 data from.
24 The msgvec argument is a pointer to an array of mmsghdr structures.
26 The size of this array is specified in vlen.
27 The mmsghdr structure is defined in <sys/socket.h> as:
29 struct mmsghdr {
31 struct msghdr msg_hdr; /* Message header */
32 unsigned int msg_len; /* Number of received bytes for header */
33 };
34 The msg_hdr field is a msghdr structure, as described in recvmsg(2).
36 The msg_len field is the number of bytes returned for the message in
37 the entry. This field has the same value as the return value of a sin‐
38 gle recvmsg(2) on the header.
39 The flags argument contains flags ORed together. The flags are the
41 same as documented for recvmsg(2), with the following addition:
42 MSG_WAITFORONE (since Linux 2.6.34)
44 Turns on MSG_DONTWAIT after the first message has been received.
45 The timeout argument points to a struct timespec (see clock_gettime(2))
47 defining a timeout (seconds plus nanoseconds) for the receive opera‐
48 tion. (This interval will be rounded up to the system clock granular‐
49 ity, and kernel scheduling delays mean that the blocking interval may
50 overrun by a small amount.) If timeout is NULL then the operation
51 blocks indefinitely.
52 A blocking recvmmsg() call blocks until vlen messages have been
54 received or until the timeout expires. A nonblocking call reads as
55 many messages as are available (up to the limit specified by vlen) and
56 returns immediately.
57 On return from recvmmsg(), successive elements of msgvec are updated to
59 contain information about each received message: msg_len contains the
60 size of the received message; the subfields of msg_hdr are updated as
61 described in recvmsg(2). The return value of the call indicates the
62 number of elements of msgvec that have been updated.
63
65 On success, recvmmsg() returns the number of messages received in
66 msgvec; on error, -1 is returned, and errno is set to indicate the
67 error.
68
70 Errors are as for recvmsg(2). In addition, the following error can
71 occur:
72 EINVAL timeout is invalid.
74
76 The recvmmsg() system call was added in Linux 2.6.33. Support in glibc
77 was added in version 2.12.
78
80 recvmmsg() is Linux-specific.
81
83 The following program uses recvmmsg() to receive multiple messages on a
84 socket and stores them in multiple buffers. The call returns if all
85 buffers are filled or if the timeout specified has expired.
86 The following snippet periodically generates UDP datagrams containing a
88 random number:
89 $ while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;
91 sleep 0.25; done
92 These datagrams are read by the example application, which can give the
94 following output:
95 $ ./a.out
97 5 messages received
98 1 11782
99 2 11345
100 3 304
101 4 13514
102 5 28421
103 Program source
105 #define _GNU_SOURCE
107 #include <netinet/ip.h>
108 #include <stdio.h>
109 #include <stdlib.h>
110 #include <string.h>
111 #include <sys/socket.h>
112 int
114 main(void)
115 {
116 #define VLEN 10
117 #define BUFSIZE 200
118 #define TIMEOUT 1
119 int sockfd, retval, i;
120 struct sockaddr_in sa;
121 struct mmsghdr msgs[VLEN];
122 struct iovec iovecs[VLEN];
123 char bufs[VLEN][BUFSIZE+1];
124 struct timespec timeout;
125 sockfd = socket(AF_INET, SOCK_DGRAM, 0);
127 if (sockfd == -1) {
128 perror("socket()");
129 exit(EXIT_FAILURE);
130 }
131 sa.sin_family = AF_INET;
133 sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
134 sa.sin_port = htons(1234);
135 if (bind(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == -1) {
136 perror("bind()");
137 exit(EXIT_FAILURE);
138 }
139 memset(msgs, 0, sizeof(msgs));
141 for (i = 0; i < VLEN; i++) {
142 iovecs[i].iov_base = bufs[i];
143 iovecs[i].iov_len = BUFSIZE;
144 msgs[i].msg_hdr.msg_iov = &iovecs[i];
145 msgs[i].msg_hdr.msg_iovlen = 1;
146 }
147 timeout.tv_sec = TIMEOUT;
149 timeout.tv_nsec = 0;
150 retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
152 if (retval == -1) {
153 perror("recvmmsg()");
154 exit(EXIT_FAILURE);
155 }
156 printf("%d messages received\n", retval);
158 for (i = 0; i < retval; i++) {
159 bufs[i][msgs[i].msg_len] = 0;
160 printf("%d %s", i+1, bufs[i]);
161 }
162 exit(EXIT_SUCCESS);
163 }
164
166 clock_gettime(2), recvmsg(2), sendmmsg(2), sendmsg(2), socket(2),
167 socket(7)
168
170 This page is part of release 3.53 of the Linux man-pages project. A
171 description of the project, and information about reporting bugs, can
172 be found at http://www.kernel.org/doc/man-pages/.
173Linux 2012-12-24 RECVMMSG(2)