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 2020-11-01 "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 EXAMPLES
 193 The following program uses
 194 .BR recvmmsg ()
 195 to receive multiple messages on a socket and stores
 196 them in multiple buffers.
 197 The call returns if all buffers are filled or if the
 198 timeout specified has expired.
 199 .PP
 200 The following snippet periodically generates UDP datagrams
 201 containing a random number:
 202 .PP
 203 .in +4n
 204 .EX
 205 .RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;"
 206 .B      "      sleep 0.25; done"
 207 .EE
 208 .in
 209 .PP
 210 These datagrams are read by the example application, which
 211 can give the following output:
 212 .PP
 213 .in +4n
 214 .EX
 215 .RB "$" " ./a.out"
 216 5 messages received
 217 1 11782
 218 2 11345
 219 3 304
 220 4 13514
 221 5 28421
 222 .EE
 223 .in
 224 .SS Program source
 225 \&
 226 .EX
 227 #define _GNU_SOURCE
 228 #include <netinet/ip.h>
 229 #include <stdio.h>
 230 #include <stdlib.h>
 231 #include <string.h>
 232 #include <sys/socket.h>
 233
 234 int
 235 main(void)
 236 {
 237 #define VLEN 10
 238 #define BUFSIZE 200
 239 #define TIMEOUT 1
 240     int sockfd, retval;
 241     struct sockaddr_in addr;
 242     struct mmsghdr msgs[VLEN];
 243     struct iovec iovecs[VLEN];
 244     char bufs[VLEN][BUFSIZE+1];
 245     struct timespec timeout;
 246
 247     sockfd = socket(AF_INET, SOCK_DGRAM, 0);
 248     if (sockfd == \-1) {
 249         perror("socket()");
 250         exit(EXIT_FAILURE);
 251     }
 252
 253     addr.sin_family = AF_INET;
 254     addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
 255     addr.sin_port = htons(1234);
 256     if (bind(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
 257         perror("bind()");
 258         exit(EXIT_FAILURE);
 259     }
 260
 261     memset(msgs, 0, sizeof(msgs));
 262     for (int i = 0; i < VLEN; i++) {
 263         iovecs[i].iov_base         = bufs[i];
 264         iovecs[i].iov_len          = BUFSIZE;
 265         msgs[i].msg_hdr.msg_iov    = &iovecs[i];
 266         msgs[i].msg_hdr.msg_iovlen = 1;
 267     }
 268
 269     timeout.tv_sec = TIMEOUT;
 270     timeout.tv_nsec = 0;
 271
 272     retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
 273     if (retval == \-1) {
 274         perror("recvmmsg()");
 275         exit(EXIT_FAILURE);
 276     }
 277
 278     printf("%d messages received\en", retval);
 279     for (int i = 0; i < retval; i++) {
 280         bufs[i][msgs[i].msg_len] = 0;
 281         printf("%d %s", i+1, bufs[i]);
 282     }
 283     exit(EXIT_SUCCESS);
 284 }
 285 .EE
 286 .SH SEE ALSO
 287 .BR clock_gettime (2),
 288 .BR recvmsg (2),
 289 .BR sendmmsg (2),
 290 .BR sendmsg (2),
 291 .BR socket (2),
 292 .BR socket (7)