man2/sendmmsg.2

   1 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" with some material from a draft by
   3 .\" Stephan Mueller <stephan.mueller@atsec.com>
   4 .\" in turn based on Andi Kleen's recvmmsg.2 page.
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .TH sendmmsg 2 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 sendmmsg \- send multiple messages on a socket
  11 .SH LIBRARY
  12 Standard C library
  13 .RI ( libc ", " \-lc )
  14 .SH SYNOPSIS
  15 .nf
  16 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  17 .B #include <sys/socket.h>
  18 .PP
  19 .BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \
  20 ", unsigned int " vlen ","
  21 .BI "             int " flags ");"
  22 .fi
  23 .SH DESCRIPTION
  24 The
  25 .BR sendmmsg ()
  26 system call is an extension of
  27 .BR sendmsg (2)
  28 that allows the caller to transmit multiple messages on a socket
  29 using a single system call.
  30 (This has performance benefits for some applications.)
  31 .\" See commit 228e548e602061b08ee8e8966f567c12aa079682
  32 .PP
  33 The
  34 .I sockfd
  35 argument is the file descriptor of the socket
  36 on which data is to be transmitted.
  37 .PP
  38 The
  39 .I msgvec
  40 argument is a pointer to an array of
  41 .I mmsghdr
  42 structures.
  43 The size of this array is specified in
  44 .IR vlen .
  45 .PP
  46 The
  47 .I mmsghdr
  48 structure is defined in
  49 .I <sys/socket.h>
  50 as:
  51 .PP
  52 .in +4n
  53 .EX
  54 struct mmsghdr {
  55     struct msghdr msg_hdr;  /* Message header */
  56     unsigned int  msg_len;  /* Number of bytes transmitted */
  57 };
  58 .EE
  59 .in
  60 .PP
  61 The
  62 .I msg_hdr
  63 field is a
  64 .I msghdr
  65 structure, as described in
  66 .BR sendmsg (2).
  67 The
  68 .I msg_len
  69 field is used to return the number of bytes sent from the message in
  70 .I msg_hdr
  71 (i.e., the same as the return value from a single
  72 .BR sendmsg (2)
  73 call).
  74 .PP
  75 The
  76 .I flags
  77 argument contains flags ORed together.
  78 The flags are the same as for
  79 .BR sendmsg (2).
  80 .PP
  81 A blocking
  82 .BR sendmmsg ()
  83 call blocks until
  84 .I vlen
  85 messages have been sent.
  86 A nonblocking call sends as many messages as possible
  87 (up to the limit specified by
  88 .IR vlen )
  89 and returns immediately.
  90 .PP
  91 On return from
  92 .BR sendmmsg (),
  93 the
  94 .I msg_len
  95 fields of successive elements of
  96 .I msgvec
  97 are updated to contain the number of bytes transmitted from the corresponding
  98 .IR msg_hdr .
  99 The return value of the call indicates the number of elements of
 100 .I msgvec
 101 that have been updated.
 102 .SH RETURN VALUE
 103 On success,
 104 .BR sendmmsg ()
 105 returns the number of messages sent from
 106 .IR msgvec ;
 107 if this is less than
 108 .IR vlen ,
 109 the caller can retry with a further
 110 .BR sendmmsg ()
 111 call to send the remaining messages.
 112 .PP
 113 On error, \-1 is returned, and
 114 .I errno
 115 is set to indicate the error.
 116 .SH ERRORS
 117 Errors are as for
 118 .BR sendmsg (2).
 119 An error is returned only if no datagrams could be sent.
 120 See also BUGS.
 121 .\" commit 728ffb86f10873aaf4abd26dde691ee40ae731fe
 122 .\"     ... only return an error if no datagrams could be sent.
 123 .\"     If less than the requested number of messages were sent, the application
 124 .\"     must retry starting at the first failed one and if the problem is
 125 .\"     persistent the error will be returned.
 126 .\"
 127 .\"     This matches the behavior of other syscalls like read/write - it
 128 .\"     is not an error if less than the requested number of elements are sent.
 129 .SH VERSIONS
 130 The
 131 .BR sendmmsg ()
 132 system call was added in Linux 3.0.
 133 Support in glibc was added in version 2.14.
 134 .SH STANDARDS
 135 .BR sendmmsg ()
 136 is Linux-specific.
 137 .SH NOTES
 138 The value specified in
 139 .I vlen
 140 is capped to
 141 .B UIO_MAXIOV
 142 (1024).
 143 .\" commit 98382f419f32d2c12d021943b87dea555677144b
 144 .\"     net: Cap number of elements for sendmmsg
 145 .\"
 146 .\"     To limit the amount of time we can spend in sendmmsg, cap the
 147 .\"     number of elements to UIO_MAXIOV (currently 1024).
 148 .\"
 149 .\"     For error handling an application using sendmmsg needs to retry at
 150 .\"     the first unsent message, so capping is simpler and requires less
 151 .\"     application logic than returning EINVAL.
 152 .SH BUGS
 153 If an error occurs after at least one message has been sent,
 154 the call succeeds, and returns the number of messages sent.
 155 The error code is lost.
 156 The caller can retry the transmission,
 157 starting at the first failed message, but there is no guarantee that,
 158 if an error is returned, it will be the same as the one that was lost
 159 on the previous call.
 160 .SH EXAMPLES
 161 The example below uses
 162 .BR sendmmsg ()
 163 to send
 164 .I onetwo
 165 and
 166 .I three
 167 in two distinct UDP datagrams using one system call.
 168 The contents of the first datagram originates from a pair of buffers.
 169 .PP
 170 .\" SRC BEGIN (sendmmsg.c)
 171 .EX
 172 #define _GNU_SOURCE
 173 #include <arpa/inet.h>
 174 #include <netinet/in.h>
 175 #include <stdio.h>
 176 #include <stdlib.h>
 177 #include <string.h>
 178 #include <sys/socket.h>
 179 #include <sys/types.h>
 180
 181 int
 182 main(void)
 183 {
 184     int                 retval;
 185     int                 sockfd;
 186     struct iovec        msg1[2], msg2;
 187     struct mmsghdr      msg[2];
 188     struct sockaddr_in  addr;
 189
 190     sockfd = socket(AF_INET, SOCK_DGRAM, 0);
 191     if (sockfd == \-1) {
 192         perror("socket()");
 193         exit(EXIT_FAILURE);
 194     }
 195
 196     addr.sin_family = AF_INET;
 197     addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
 198     addr.sin_port = htons(1234);
 199     if (connect(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
 200         perror("connect()");
 201         exit(EXIT_FAILURE);
 202     }
 203
 204     memset(msg1, 0, sizeof(msg1));
 205     msg1[0].iov_base = "one";
 206     msg1[0].iov_len = 3;
 207     msg1[1].iov_base = "two";
 208     msg1[1].iov_len = 3;
 209
 210     memset(&msg2, 0, sizeof(msg2));
 211     msg2.iov_base = "three";
 212     msg2.iov_len = 5;
 213
 214     memset(msg, 0, sizeof(msg));
 215     msg[0].msg_hdr.msg_iov = msg1;
 216     msg[0].msg_hdr.msg_iovlen = 2;
 217
 218     msg[1].msg_hdr.msg_iov = &msg2;
 219     msg[1].msg_hdr.msg_iovlen = 1;
 220
 221     retval = sendmmsg(sockfd, msg, 2, 0);
 222     if (retval == \-1)
 223         perror("sendmmsg()");
 224     else
 225         printf("%d messages sent\en", retval);
 226
 227     exit(0);
 228 }
 229 .EE
 230 .\" SRC END
 231 .SH SEE ALSO
 232 .BR recvmmsg (2),
 233 .BR sendmsg (2),
 234 .BR socket (2),
 235 .BR socket (7)