original/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 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .TH RECVMMSG 2 2011-10-04 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 recvmmsg \- receive multiple messages on a socket
  27 .SH SYNOPSIS
  28 .nf
  29 .B "#define _GNU_SOURCE"
  30 .BI "#include <sys/socket.h>"
  31
  32 .BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \
  33 ", unsigned int " vlen ","
  34 .br
  35 .BI "             unsigned int " flags ", struct timespec *" timeout ");"
  36 .fi
  37 .SH DESCRIPTION
  38 The
  39 .BR recvmmsg ()
  40 system call is an extension of
  41 .BR recvmsg (2)
  42 that allows the caller to receive multiple messages from a socket
  43 using a single system call.
  44 (This has performance benefits for some applications.)
  45 A further extension over
  46 .BR recvmsg (2)
  47 is support for a timeout on the receive operation.
  48
  49 The
  50 .I sockfd
  51 argument is the file descriptor of the socket to receive data from.
  52
  53 The
  54 .I msgvec
  55 argument is a pointer to an array of
  56 .I mmsghdr
  57 structures.
  58 The size of this array is specified in
  59 .IR vlen .
  60
  61 The
  62 .I mmsghdr
  63 structure is defined in
  64 .I <sys/socket.h>
  65 as:
  66
  67 .in +4n
  68 .nf
  69 struct mmsghdr {
  70     struct msghdr msg_hdr;  /* Message header */
  71     unsigned int  msg_len;  /* Number of received bytes for header */
  72 };
  73 .fi
  74 .in
  75 .PP
  76 The
  77 .I msg_hdr
  78 field is a
  79 .I msghdr
  80 structure, as described in
  81 .BR recvmsg (2).
  82 The
  83 .I msg_len
  84 field is the number of bytes returned for the message in the entry.
  85 This field has the same value as the return value of a single
  86 .BR recvmsg (2)
  87 on the header.
  88
  89 The
  90 .I flags
  91 argument contains flags ORed together.
  92 The flags are the same as documented for
  93 .BR recvmsg (2),
  94 with the following addition:
  95 .TP
  96 .B MSG_WAITFORONE
  97 Turns on
  98 .B MSG_DONTWAIT
  99 after the first message has been received.
 100 .PP
 101 The
 102 .I timeout
 103 argument points to a
 104 .I struct timespec
 105 (see
 106 .BR clock_gettime (2))
 107 defining a timeout (seconds plus nanoseconds) for the receive operation.
 108 If
 109 .I timeout
 110 is
 111 .I NULL
 112 then the operation blocks indefinitely.
 113
 114 A blocking
 115 .BR recvmmsg ()
 116 call blocks until
 117 .I vlen
 118 messages have been received
 119 or until the timeout expires.
 120 A nonblocking call reads as many messages as are available
 121 (up to the limit specified by
 122 .IR vlen )
 123 and returns immediately.
 124
 125 On return from
 126 .BR recvmmsg (),
 127 successive elements of
 128 .IR msgvec
 129 are updated to contain information about each received message:
 130 .I msg_len
 131 contains the size of the received message;
 132 the subfields of
 133 .I msg_hdr
 134 are updated as described in
 135 .BR recvmsg (2).
 136 The return value of the call indicates the number of elements of
 137 .I msgvec
 138 that have been updated.
 139 .SH RETURN VALUE
 140 On success,
 141 .BR recvmmsg ()
 142 returns the number of messages received in
 143 .IR msgvec ;
 144 on error, \-1 is returned, and
 145 .I errno
 146 is set to indicate the error.
 147 .SH ERRORS
 148 Errors are as for
 149 .BR recvmsg (2).
 150 In addition, the following error can occur:
 151 .TP
 152 .B EINVAL
 153 .I timeout
 154 is invalid.
 155 .SH VERSIONS
 156 The
 157 .BR recvmmsg ()
 158 system call was added in Linux 2.6.32.
 159 Support in glibc was added in version 2.12.
 160 .SH CONFORMING TO
 161 .BR recvmmsg ()
 162 is Linux-specific.
 163 .SH SEE ALSO
 164 .BR clock_gettime (2),
 165 .BR recvmsg (2),
 166 .BR sendmmsg (2),
 167 .BR sendmsg (2),
 168 .BR socket (2),
 169 .BR socket (7)