Debian Codegraph @

upstream/debian-unstable/man2/sendmmsg.2

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