]> git.ipfire.org Git - thirdparty/man-pages.git/blob - man2/sendmmsg.2
Many pages: Fix style issues reported by `make lint-groff`
[thirdparty/man-pages.git] / 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 2020-06-09 "Linux" "Linux Programmer's Manual"
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 CONFORMING TO
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 .EX
171 #define _GNU_SOURCE
172 #include <netinet/ip.h>
173 #include <stdio.h>
174 #include <stdlib.h>
175 #include <string.h>
176 #include <sys/types.h>
177 #include <sys/socket.h>
178
179 int
180 main(void)
181 {
182 int sockfd;
183 struct sockaddr_in addr;
184 struct mmsghdr msg[2];
185 struct iovec msg1[2], msg2;
186 int retval;
187
188 sockfd = socket(AF_INET, SOCK_DGRAM, 0);
189 if (sockfd == \-1) {
190 perror("socket()");
191 exit(EXIT_FAILURE);
192 }
193
194 addr.sin_family = AF_INET;
195 addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
196 addr.sin_port = htons(1234);
197 if (connect(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
198 perror("connect()");
199 exit(EXIT_FAILURE);
200 }
201
202 memset(msg1, 0, sizeof(msg1));
203 msg1[0].iov_base = "one";
204 msg1[0].iov_len = 3;
205 msg1[1].iov_base = "two";
206 msg1[1].iov_len = 3;
207
208 memset(&msg2, 0, sizeof(msg2));
209 msg2.iov_base = "three";
210 msg2.iov_len = 5;
211
212 memset(msg, 0, sizeof(msg));
213 msg[0].msg_hdr.msg_iov = msg1;
214 msg[0].msg_hdr.msg_iovlen = 2;
215
216 msg[1].msg_hdr.msg_iov = &msg2;
217 msg[1].msg_hdr.msg_iovlen = 1;
218
219 retval = sendmmsg(sockfd, msg, 2, 0);
220 if (retval == \-1)
221 perror("sendmmsg()");
222 else
223 printf("%d messages sent\en", retval);
224
225 exit(0);
226 }
227 .EE
228 .SH SEE ALSO
229 .BR recvmmsg (2),
230 .BR sendmsg (2),
231 .BR socket (2),
232 .BR socket (7)