Debian Codegraph @

upstream/debian-trixie/man2/sendmmsg.2

raw
1 .\" Copyright (c) 2012 by Michael Kerrisk <[email protected]>
2 .\" with some material from a draft by
3 .\" Stephan Mueller <[email protected]>
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 2024-06-15 "Linux man-pages 6.9.1"
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 .P
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 .P
33 The
34 .I sockfd
35 argument is the file descriptor of the socket
36 on which data is to be transmitted.
37 .P
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 .P
46 The
47 .I mmsghdr
48 structure is defined in
49 .I <sys/socket.h>
50 as:
51 .P
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 .P
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 .P
75 The
76 .I flags
77 argument contains flags ORed together.
78 The flags are the same as for
79 .BR sendmsg (2).
80 .P
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 .P
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 .P
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 STANDARDS
130 Linux.
131 .SH HISTORY
132 Linux 3.0,
133 glibc 2.14.
134 .SH NOTES
135 The value specified in
136 .I vlen
137 is capped to
138 .B UIO_MAXIOV
139 (1024).
140 .\" commit 98382f419f32d2c12d021943b87dea555677144b
141 .\" net: Cap number of elements for sendmmsg
142 .\"
143 .\" To limit the amount of time we can spend in sendmmsg, cap the
144 .\" number of elements to UIO_MAXIOV (currently 1024).
145 .\"
146 .\" For error handling an application using sendmmsg needs to retry at
147 .\" the first unsent message, so capping is simpler and requires less
148 .\" application logic than returning EINVAL.
149 .SH BUGS
150 If an error occurs after at least one message has been sent,
151 the call succeeds, and returns the number of messages sent.
152 The error code is lost.
153 The caller can retry the transmission,
154 starting at the first failed message, but there is no guarantee that,
155 if an error is returned, it will be the same as the one that was lost
156 on the previous call.
157 .SH EXAMPLES
158 The example below uses
159 .BR sendmmsg ()
160 to send
161 .I onetwo
162 and
163 .I three
164 in two distinct UDP datagrams using one system call.
165 The contents of the first datagram originates from a pair of buffers.
166 .P
167 .\" SRC BEGIN (sendmmsg.c)
168 .EX
169 #define _GNU_SOURCE
170 #include <arpa/inet.h>
171 #include <netinet/in.h>
172 #include <stdio.h>
173 #include <stdlib.h>
174 #include <string.h>
175 #include <sys/socket.h>
176 #include <sys/types.h>
177 \&
178 int
179 main(void)
180 {
181 int retval;
182 int sockfd;
183 struct iovec msg1[2], msg2;
184 struct mmsghdr msg[2];
185 struct sockaddr_in addr;
186 \&
187 sockfd = socket(AF_INET, SOCK_DGRAM, 0);
188 if (sockfd == \-1) {
189 perror("socket()");
190 exit(EXIT_FAILURE);
191 }
192 \&
193 addr.sin_family = AF_INET;
194 addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
195 addr.sin_port = htons(1234);
196 if (connect(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
197 perror("connect()");
198 exit(EXIT_FAILURE);
199 }
200 \&
201 memset(msg1, 0, sizeof(msg1));
202 msg1[0].iov_base = "one";
203 msg1[0].iov_len = 3;
204 msg1[1].iov_base = "two";
205 msg1[1].iov_len = 3;
206 \&
207 memset(&msg2, 0, sizeof(msg2));
208 msg2.iov_base = "three";
209 msg2.iov_len = 5;
210 \&
211 memset(msg, 0, sizeof(msg));
212 msg[0].msg_hdr.msg_iov = msg1;
213 msg[0].msg_hdr.msg_iovlen = 2;
214 \&
215 msg[1].msg_hdr.msg_iov = &msg2;
216 msg[1].msg_hdr.msg_iovlen = 1;
217 \&
218 retval = sendmmsg(sockfd, msg, 2, 0);
219 if (retval == \-1)
220 perror("sendmmsg()");
221 else
222 printf("%d messages sent\[rs]n", retval);
223 \&
224 exit(0);
225 }
226 .EE
227 .\" SRC END
228 .SH SEE ALSO
229 .BR recvmmsg (2),
230 .BR sendmsg (2),
231 .BR socket (2),
232 .BR socket (7)