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 2020-11-01 "Linux" "Linux Programmer's Manual"
  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 CONFORMING TO
 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 .EX
 210 #define _GNU_SOURCE
 211 #include <netinet/ip.h>
 212 #include <stdio.h>
 213 #include <stdlib.h>
 214 #include <string.h>
 215 #include <sys/socket.h>
 216
 217 int
 218 main(void)
 219 {
 220 #define VLEN 10
 221 #define BUFSIZE 200
 222 #define TIMEOUT 1
 223     int sockfd, retval;
 224     struct sockaddr_in addr;
 225     struct mmsghdr msgs[VLEN];
 226     struct iovec iovecs[VLEN];
 227     char bufs[VLEN][BUFSIZE+1];
 228     struct timespec timeout;
 229
 230     sockfd = socket(AF_INET, SOCK_DGRAM, 0);
 231     if (sockfd == \-1) {
 232         perror("socket()");
 233         exit(EXIT_FAILURE);
 234     }
 235
 236     addr.sin_family = AF_INET;
 237     addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
 238     addr.sin_port = htons(1234);
 239     if (bind(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
 240         perror("bind()");
 241         exit(EXIT_FAILURE);
 242     }
 243
 244     memset(msgs, 0, sizeof(msgs));
 245     for (int i = 0; i < VLEN; i++) {
 246         iovecs[i].iov_base         = bufs[i];
 247         iovecs[i].iov_len          = BUFSIZE;
 248         msgs[i].msg_hdr.msg_iov    = &iovecs[i];
 249         msgs[i].msg_hdr.msg_iovlen = 1;
 250     }
 251
 252     timeout.tv_sec = TIMEOUT;
 253     timeout.tv_nsec = 0;
 254
 255     retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
 256     if (retval == \-1) {
 257         perror("recvmmsg()");
 258         exit(EXIT_FAILURE);
 259     }
 260
 261     printf("%d messages received\en", retval);
 262     for (int i = 0; i < retval; i++) {
 263         bufs[i][msgs[i].msg_len] = 0;
 264         printf("%d %s", i+1, bufs[i]);
 265     }
 266     exit(EXIT_SUCCESS);
 267 }
 268 .EE
 269 .SH SEE ALSO
 270 .BR clock_gettime (2),
 271 .BR recvmsg (2),
 272 .BR sendmmsg (2),
 273 .BR sendmsg (2),
 274 .BR socket (2),
 275 .BR socket (7)