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