Debian Codegraph @

upstream/debian-unstable/man2/send.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .TH send 2 2025-10-29 "Linux man-pages 6.18"
7 .SH NAME
8 send, sendto, sendmsg \- send a message on a socket
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/socket.h>
15 .P
16 .BR "ssize_t send(" "size_t size;"
17 .BI " int " sockfd ", const void " buf [ size "], size_t " size \
18 ", int " flags );
19 .BR "ssize_t sendto(" "size_t size;"
20 .BI " int " sockfd ", const void " buf [ size "], size_t " size \
21 ", int " flags ,
22 .BI " const struct sockaddr *" dest_addr ", socklen_t " addrlen );
23 .BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \
24 ", int " flags );
25 .fi
26 .SH DESCRIPTION
27 The system calls
28 .BR send (),
29 .BR sendto (),
30 and
31 .BR sendmsg ()
32 are used to transmit a message to another socket.
33 .P
34 The
35 .BR send ()
36 call may be used only when the socket is in a
37 .I connected
38 state (so that the intended recipient is known).
39 The only difference between
40 .BR send ()
41 and
42 .BR write (2)
43 is the presence of
44 .IR flags .
45 With a zero
46 .I flags
47 argument,
48 .BR send ()
49 is equivalent to
50 .BR write (2).
51 Also, the following call
52 .P
53 .in +4n
54 .EX
55 send(sockfd, buf, size, flags);
56 .EE
57 .in
58 .P
59 is equivalent to
60 .P
61 .in +4n
62 .EX
63 sendto(sockfd, buf, size, flags, NULL, 0);
64 .EE
65 .in
66 .P
67 The argument
68 .I sockfd
69 is the file descriptor of the sending socket.
70 .P
71 If
72 .BR sendto ()
73 is used on a connection-mode
74 .RB ( SOCK_STREAM ,
75 .BR SOCK_SEQPACKET )
76 socket, the arguments
77 .I dest_addr
78 and
79 .I addrlen
80 are ignored (and the error
81 .B EISCONN
82 may be returned when they are
83 not NULL and 0), and the error
84 .B ENOTCONN
85 is returned when the socket was not actually connected.
86 Otherwise, the address of the target is given by
87 .I dest_addr
88 with
89 .I addrlen
90 specifying its size.
91 For
92 .BR sendmsg (),
93 the address of the target is given by
94 .IR msg.msg_name ,
95 with
96 .I msg.msg_namelen
97 specifying its size.
98 .P
99 For
100 .BR send ()
101 and
102 .BR sendto (),
103 the message is found in
104 .I buf
105 and has size
106 .IR size .
107 For
108 .BR sendmsg (),
109 the message is pointed to by the elements of the array
110 .IR msg.msg_iov .
111 The
112 .BR sendmsg ()
113 call also allows sending ancillary data (also known as control information).
114 .P
115 If the message is too long to pass atomically through the
116 underlying protocol, the error
117 .B EMSGSIZE
118 is returned, and the message is not transmitted.
119 .P
120 No indication of failure to deliver is implicit in a
121 .BR send ().
122 Locally detected errors are indicated by a return value of \-1.
123 .P
124 When the message does not fit into the send buffer of the socket,
125 .BR send ()
126 normally blocks, unless the socket has been placed in nonblocking I/O
127 mode.
128 In nonblocking mode it would fail with the error
129 .B EAGAIN
130 or
131 .B EWOULDBLOCK
132 in this case.
133 The
134 .BR select (2)
135 call may be used to determine when it is possible to send more data.
136 .SS The flags argument
137 The
138 .I flags
139 argument is the bitwise OR
140 of zero or more of the following flags.
141 .\" FIXME . ? document MSG_PROXY (which went away in Linux 2.3.15)
142 .TP
143 .BR MSG_CONFIRM " (since Linux 2.3.15)"
144 Tell the link layer that forward progress happened: you got a successful
145 reply from the other side.
146 If the link layer doesn't get this
147 it will regularly reprobe the neighbor (e.g., via a unicast ARP).
148 Valid only on
149 .B SOCK_DGRAM
150 and
151 .B SOCK_RAW
152 sockets and currently implemented only for IPv4 and IPv6.
153 See
154 .BR arp (7)
155 for details.
156 .TP
157 .B MSG_DONTROUTE
158 Don't use a gateway to send out the packet,
159 send to hosts only
160 on directly connected networks.
161 This is usually used only
162 by diagnostic or routing programs.
163 This is defined only for
164 protocol families that route;
165 packet sockets don't.
166 .TP
167 .BR MSG_DONTWAIT " (since Linux 2.2)"
168 Enables nonblocking operation;
169 if the operation would block,
170 .B EAGAIN
171 or
172 .B EWOULDBLOCK
173 is returned.
174 This provides similar behavior to setting the
175 .B O_NONBLOCK
176 flag (via the
177 .BR fcntl (2)
178 .B F_SETFL
179 operation), but differs in that
180 .B MSG_DONTWAIT
181 is a per-call option, whereas
182 .B O_NONBLOCK
183 is a setting on the open file description (see
184 .BR open (2)),
185 which will affect all threads in the calling process
186 as well as other processes that hold file descriptors
187 referring to the same open file description.
188 .TP
189 .BR MSG_EOR " (since Linux 2.2)"
190 Terminates a record (when this notion is supported, as for sockets of type
191 .BR SOCK_SEQPACKET ).
192 .TP
193 .BR MSG_MORE " (since Linux 2.4.4)"
194 The caller has more data to send.
195 This flag is used with TCP sockets to obtain the same effect
196 as the
197 .B TCP_CORK
198 socket option (see
199 .BR tcp (7)),
200 with the difference that this flag can be set on a per-call basis.
201 .IP
202 Since Linux 2.6, this flag is also supported for UDP sockets, and informs
203 the kernel to package all of the data sent in calls with this flag set
204 into a single datagram which is transmitted only when a call is performed
205 that does not specify this flag.
206 (See also the
207 .B UDP_CORK
208 socket option described in
209 .BR udp (7).)
210 .TP
211 .BR MSG_NOSIGNAL " (since Linux 2.2)"
212 Don't generate a
213 .B SIGPIPE
214 signal if the peer on a stream-oriented socket has closed the connection.
215 The
216 .B EPIPE
217 error is still returned.
218 This provides similar behavior to using
219 .BR sigaction (2)
220 to ignore
221 .BR SIGPIPE ,
222 but, whereas
223 .B MSG_NOSIGNAL
224 is a per-call feature,
225 ignoring
226 .B SIGPIPE
227 sets a process attribute that affects all threads in the process.
228 .TP
229 .B MSG_OOB
230 Sends
231 .I out-of-band
232 data on sockets that support this notion (e.g., of type
233 .BR SOCK_STREAM );
234 the underlying protocol must also support
235 .I out-of-band
236 data.
237 .TP
238 .BR MSG_FASTOPEN " (since Linux 3.7)"
239 Attempts TCP Fast Open (RFC7413) and sends data in the SYN like a
240 combination of
241 .BR connect (2)
242 and
243 .BR write (2),
244 by performing an implicit
245 .BR connect (2)
246 operation.
247 It blocks until the data is buffered and the handshake has completed.
248 For a non-blocking socket,
249 it returns the number of bytes buffered and sent in the SYN packet.
250 If the cookie is not available locally,
251 it returns
252 .BR EINPROGRESS ,
253 and sends a SYN with a Fast Open cookie request automatically.
254 The caller needs to write the data again when the socket is connected.
255 On errors,
256 it sets the same
257 .I errno
258 as
259 .BR connect (2)
260 if the handshake fails.
261 This flag requires enabling TCP Fast Open client support on sysctl
262 .IR net.ipv4.tcp_fastopen .
263 .IP
264 Refer to
265 .B TCP_FASTOPEN_CONNECT
266 socket option in
267 .BR tcp (7)
268 for an alternative approach.
269 .SS sendmsg()
270 The definition of the
271 .I msghdr
272 structure employed by
273 .BR sendmsg ()
274 is as follows:
275 .P
276 .in +4n
277 .EX
278 struct msghdr {
279 void *msg_name; /* Optional address */
280 socklen_t msg_namelen; /* Size of address */
281 struct iovec *msg_iov; /* Scatter/gather array */
282 size_t msg_iovlen; /* # elements in msg_iov */
283 void *msg_control; /* Ancillary data, see below */
284 size_t msg_controllen; /* Ancillary data buffer size */
285 int msg_flags; /* Flags (unused) */
286 };
287 .EE
288 .in
289 .P
290 The
291 .I msg_name
292 field is used on an unconnected socket to specify
293 the target address for a datagram.
294 It points to a buffer containing the address;
295 the
296 .I msg_namelen
297 field should be set to the size of the address.
298 For a connected socket, these fields should be specified as NULL and 0,
299 respectively.
300 .P
301 The
302 .I msg_iov
303 and
304 .I msg_iovlen
305 fields specify scatter-gather locations, as for
306 .BR writev (2).
307 .P
308 You may send control information (ancillary data) using the
309 .I msg_control
310 and
311 .I msg_controllen
312 members.
313 The maximum control buffer size the kernel can process is limited
314 per socket by the value in
315 .IR /proc/sys/net/core/optmem_max ;
316 see
317 .BR socket (7).
318 For further information on the use of ancillary data in various
319 socket domains, see
320 .BR unix (7)
321 and
322 .BR ip (7).
323 .P
324 The
325 .I msg_flags
326 field is ignored.
327 .\" Still to be documented:
328 .\" Send file descriptors and user credentials using the
329 .\" msg_control* fields.
330 .SH RETURN VALUE
331 On success, these calls return the number of bytes sent.
332 On error, \-1 is returned, and
333 .I errno
334 is set to indicate the error.
335 .SH ERRORS
336 These are some standard errors generated by the socket layer.
337 Additional errors
338 may be generated and returned from the underlying protocol modules;
339 see their respective manual pages.
340 .TP
341 .B EACCES
342 (For UNIX domain sockets, which are identified by pathname)
343 Write permission is denied on the destination socket file,
344 or search permission is denied for one of the directories
345 the path prefix.
346 (See
347 .BR path_resolution (7).)
348 .IP
349 (For UDP sockets) An attempt was made to send to a
350 network/broadcast address as though it was a unicast address.
351 .TP
352 .BR EAGAIN " or " EWOULDBLOCK
353 .\" Actually EAGAIN on Linux
354 The socket is marked nonblocking and the requested operation
355 would block.
356 POSIX.1-2001 allows either error to be returned for this case,
357 and does not require these constants to have the same value,
358 so a portable application should check for both possibilities.
359 .TP
360 .B EAGAIN
361 (Internet domain datagram sockets)
362 The socket referred to by
363 .I sockfd
364 had not previously been bound to an address and,
365 upon attempting to bind it to an ephemeral port,
366 it was determined that all port numbers in the ephemeral port range
367 are currently in use.
368 See the discussion of
369 .I /proc/sys/net/ipv4/ip_local_port_range
370 in
371 .BR ip (7).
372 .TP
373 .B EALREADY
374 Another Fast Open is in progress.
375 .TP
376 .B EBADF
377 .I sockfd
378 is not a valid open file descriptor.
379 .TP
380 .B ECONNRESET
381 Connection reset by peer.
382 .TP
383 .B EDESTADDRREQ
384 The socket is not connection-mode, and no peer address is set.
385 .TP
386 .B EFAULT
387 An invalid user space address was specified for an argument.
388 .TP
389 .B EINTR
390 A signal occurred before any data was transmitted;
391 see
392 .BR signal (7).
393 .TP
394 .B EINVAL
395 Invalid argument passed.
396 .TP
397 .B EISCONN
398 The connection-mode socket was connected already but a
399 recipient was specified.
400 (Now either this error is returned, or the recipient specification
401 is ignored.)
402 .TP
403 .B EMSGSIZE
404 The socket type
405 .\" (e.g., SOCK_DGRAM )
406 requires that message be sent atomically, and the size
407 of the message to be sent made this impossible.
408 .TP
409 .B ENOBUFS
410 The output queue for a network interface was full.
411 This generally indicates that the interface has stopped sending,
412 but may be caused by transient congestion.
413 (Normally, this does not occur in Linux.
414 Packets are just silently dropped
415 when a device queue overflows.)
416 .TP
417 .B ENOMEM
418 No memory available.
419 .TP
420 .B ENOTCONN
421 The socket is not connected, and no target has been given.
422 .TP
423 .B ENOTSOCK
424 The file descriptor
425 .I sockfd
426 does not refer to a socket.
427 .TP
428 .B EOPNOTSUPP
429 Some bit in the
430 .I flags
431 argument is inappropriate for the socket type.
432 .TP
433 .B EPIPE
434 The local end has been shut down on a connection oriented socket.
435 In this case, the process
436 will also receive a
437 .B SIGPIPE
438 unless
439 .B MSG_NOSIGNAL
440 is set.
441 .SH VERSIONS
442 According to POSIX.1-2001, the
443 .I msg_controllen
444 field of the
445 .I msghdr
446 structure should be typed as
447 .IR socklen_t ,
448 and the
449 .I msg_iovlen
450 field should be typed as
451 .IR int ,
452 but glibc currently types both as
453 .IR size_t .
454 .\" glibc bug for msg_controllen raised 12 Mar 2006
455 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
456 .\" The problem is an underlying kernel issue: the size of the
457 .\" __kernel_size_t type used to type these fields varies
458 .\" across architectures, but socklen_t is always 32 bits,
459 .\" as (at least with GCC) is int.
460 .SH STANDARDS
461 POSIX.1-2024.
462 .P
463 .B MSG_CONFIRM
464 is a Linux extension.
465 .SH HISTORY
466 4.4BSD, SVr4, POSIX.1-2001.
467 (first appeared in 4.2BSD).
468 .P
469 POSIX.1-2001 describes only the
470 .B MSG_OOB
471 and
472 .B MSG_EOR
473 flags.
474 POSIX.1-2008 adds a specification of
475 .BR MSG_NOSIGNAL .
476 .SH NOTES
477 See
478 .BR sendmmsg (2)
479 for information about a Linux-specific system call
480 that can be used to transmit multiple datagrams in a single call.
481 .SH BUGS
482 Linux may return
483 .B EPIPE
484 instead of
485 .BR ENOTCONN .
486 .SH EXAMPLES
487 An example of the use of
488 .BR sendto ()
489 is shown in
490 .BR getaddrinfo (3).
491 .SH SEE ALSO
492 .BR fcntl (2),
493 .BR getsockopt (2),
494 .BR recv (2),
495 .BR select (2),
496 .BR sendfile (2),
497 .BR sendmmsg (2),
498 .BR shutdown (2),
499 .BR socket (2),
500 .BR write (2),
501 .BR cmsg (3),
502 .BR ip (7),
503 .BR ipv6 (7),
504 .BR socket (7),
505 .BR tcp (7),
506 .BR udp (7),
507 .BR unix (7)