man2/recvmmsg.2

   1 .\" Copyright (C) 2011 by Andi Kleen <andi@firstfloor.org>
   2 .\" and Copyright (c) 2011 by Michael Kerrisk <mtk.manpages@gmail.com>
   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 <acme@redhat.com>
   9 .\"     Date:   Mon Oct 12 23:40:10 2009 -0700
  10 .\"
  11 .TH recvmmsg 2 (date) "Linux man-pages (unreleased)"
  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 .PP
  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 .PP
  38 The
  39 .I sockfd
  40 argument is the file descriptor of the socket to receive data from.
  41 .PP
  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 .PP
  50 The
  51 .I mmsghdr
  52 structure is defined in
  53 .I <sys/socket.h>
  54 as:
  55 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
 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 .PP
 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 .PP
 147 See also BUGS.
 148 .SH VERSIONS
 149 The
 150 .BR recvmmsg ()
 151 system call was added in Linux 2.6.33.
 152 Support in glibc was added in version 2.12.
 153 .SH STANDARDS
 154 .BR recvmmsg ()
 155 is Linux-specific.
 156 .SH BUGS
 157 The
 158 .I timeout
 159 argument does not work as intended.
 160 .\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=75371
 161 .\" http://thread.gmane.org/gmane.linux.man/5677
 162 The timeout is checked only after the receipt of each datagram,
 163 so that if up to
 164 .I vlen\-1
 165 datagrams are received before the timeout expires,
 166 but then no further datagrams are received, the call will block forever.
 167 .PP
 168 If an error occurs after at least one message has been received,
 169 the call succeeds, and returns the number of messages received.
 170 The error code is expected to be returned on a subsequent call to
 171 .BR recvmmsg ().
 172 In the current implementation, however, the error code can be overwritten
 173 in the meantime by an unrelated network event on a socket,
 174 for example an incoming ICMP packet.
 175 .SH EXAMPLES
 176 The following program uses
 177 .BR recvmmsg ()
 178 to receive multiple messages on a socket and stores
 179 them in multiple buffers.
 180 The call returns if all buffers are filled or if the
 181 timeout specified has expired.
 182 .PP
 183 The following snippet periodically generates UDP datagrams
 184 containing a random number:
 185 .PP
 186 .in +4n
 187 .EX
 188 .RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;"
 189 .B      "      sleep 0.25; done"
 190 .EE
 191 .in
 192 .PP
 193 These datagrams are read by the example application, which
 194 can give the following output:
 195 .PP
 196 .in +4n
 197 .EX
 198 .RB "$" " ./a.out"
 199 5 messages received
 200 1 11782
 201 2 11345
 202 3 304
 203 4 13514
 204 5 28421
 205 .EE
 206 .in
 207 .SS Program source
 208 \&
 209 .\" SRC BEGIN (recvmmsg.c)
 210 .EX
 211 #define _GNU_SOURCE
 212 #include <arpa/inet.h>
 213 #include <netinet/in.h>
 214 #include <stdio.h>
 215 #include <stdlib.h>
 216 #include <string.h>
 217 #include <sys/socket.h>
 218 #include <time.h>
 219
 220 int
 221 main(void)
 222 {
 223 #define VLEN 10
 224 #define BUFSIZE 200
 225 #define TIMEOUT 1
 226     int                 sockfd, retval;
 227     char                bufs[VLEN][BUFSIZE+1];
 228     struct iovec        iovecs[VLEN];
 229     struct mmsghdr      msgs[VLEN];
 230     struct timespec     timeout;
 231     struct sockaddr_in  addr;
 232
 233     sockfd = socket(AF_INET, SOCK_DGRAM, 0);
 234     if (sockfd == \-1) {
 235         perror("socket()");
 236         exit(EXIT_FAILURE);
 237     }
 238
 239     addr.sin_family = AF_INET;
 240     addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
 241     addr.sin_port = htons(1234);
 242     if (bind(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
 243         perror("bind()");
 244         exit(EXIT_FAILURE);
 245     }
 246
 247     memset(msgs, 0, sizeof(msgs));
 248     for (size_t i = 0; i < VLEN; i++) {
 249         iovecs[i].iov_base         = bufs[i];
 250         iovecs[i].iov_len          = BUFSIZE;
 251         msgs[i].msg_hdr.msg_iov    = &iovecs[i];
 252         msgs[i].msg_hdr.msg_iovlen = 1;
 253     }
 254
 255     timeout.tv_sec = TIMEOUT;
 256     timeout.tv_nsec = 0;
 257
 258     retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
 259     if (retval == \-1) {
 260         perror("recvmmsg()");
 261         exit(EXIT_FAILURE);
 262     }
 263
 264     printf("%d messages received\en", retval);
 265     for (size_t i = 0; i < retval; i++) {
 266         bufs[i][msgs[i].msg_len] = 0;
 267         printf("%zu %s", i+1, bufs[i]);
 268     }
 269     exit(EXIT_SUCCESS);
 270 }
 271 .EE
 272 .\" SRC END
 273 .SH SEE ALSO
 274 .BR clock_gettime (2),
 275 .BR recvmsg (2),
 276 .BR sendmmsg (2),
 277 .BR sendmsg (2),
 278 .BR socket (2),
 279 .BR socket (7)