readv2: Note preadv2(..., RWF_NOWAIT) bug in BUGS section
[man-pages.git] / man2 / send.2
blobfd28fed9087f1532b1d79294680a57207c2c556e
1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\"    must display the following acknowledgement:
15 .\"     This product includes software developed by the University of
16 .\"     California, Berkeley and its contributors.
17 .\" 4. Neither the name of the University nor the names of its contributors
18 .\"    may be used to endorse or promote products derived from this software
19 .\"    without specific prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\" %%%LICENSE_END
33 .\"
34 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
35 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
36 .\" Modified Oct 1998 by Andi Kleen
37 .\" Modified Oct 2003 by aeb
38 .\" Modified 2004-07-01 by mtk
39 .\"
40 .TH SEND 2 2021-03-22 "Linux" "Linux Programmer's Manual"
41 .SH NAME
42 send, sendto, sendmsg \- send a message on a socket
43 .SH SYNOPSIS
44 .nf
45 .B #include <sys/socket.h>
46 .PP
47 .BI "ssize_t send(int " sockfd ", const void *" buf ", size_t " len \
48 ", int " flags );
49 .BI "ssize_t sendto(int " sockfd ", const void *" buf ", size_t " len \
50 ", int " flags ,
51 .BI "               const struct sockaddr *" dest_addr ", socklen_t " addrlen );
52 .BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \
53 ", int " flags );
54 .fi
55 .SH DESCRIPTION
56 The system calls
57 .BR send (),
58 .BR sendto (),
59 and
60 .BR sendmsg ()
61 are used to transmit a message to another socket.
62 .PP
63 The
64 .BR send ()
65 call may be used only when the socket is in a
66 .I connected
67 state (so that the intended recipient is known).
68 The only difference between
69 .BR send ()
70 and
71 .BR write (2)
72 is the presence of
73 .IR flags .
74 With a zero
75 .I flags
76 argument,
77 .BR send ()
78 is equivalent to
79 .BR write (2).
80 Also, the following call
81 .PP
82     send(sockfd, buf, len, flags);
83 .PP
84 is equivalent to
85 .PP
86     sendto(sockfd, buf, len, flags, NULL, 0);
87 .PP
88 The argument
89 .I sockfd
90 is the file descriptor of the sending socket.
91 .PP
93 .BR sendto ()
94 is used on a connection-mode
95 .RB ( SOCK_STREAM ,
96 .BR SOCK_SEQPACKET )
97 socket, the arguments
98 .I dest_addr
99 and
100 .I addrlen
101 are ignored (and the error
102 .B EISCONN
103 may be returned when they are
104 not NULL and 0), and the error
105 .B ENOTCONN
106 is returned when the socket was not actually connected.
107 Otherwise, the address of the target is given by
108 .I dest_addr
109 with
110 .I addrlen
111 specifying its size.
113 .BR sendmsg (),
114 the address of the target is given by
115 .IR msg.msg_name ,
116 with
117 .I msg.msg_namelen
118 specifying its size.
121 .BR send ()
123 .BR sendto (),
124 the message is found in
125 .I buf
126 and has length
127 .IR len .
129 .BR sendmsg (),
130 the message is pointed to by the elements of the array
131 .IR msg.msg_iov .
133 .BR sendmsg ()
134 call also allows sending ancillary data (also known as control information).
136 If the message is too long to pass atomically through the
137 underlying protocol, the error
138 .B EMSGSIZE
139 is returned, and the message is not transmitted.
141 No indication of failure to deliver is implicit in a
142 .BR send ().
143 Locally detected errors are indicated by a return value of \-1.
145 When the message does not fit into the send buffer of the socket,
146 .BR send ()
147 normally blocks, unless the socket has been placed in nonblocking I/O
148 mode.
149 In nonblocking mode it would fail with the error
150 .B EAGAIN
152 .B EWOULDBLOCK
153 in this case.
155 .BR select (2)
156 call may be used to determine when it is possible to send more data.
157 .SS The flags argument
159 .I flags
160 argument is the bitwise OR
161 of zero or more of the following flags.
162 .\" FIXME . ? document MSG_PROXY (which went away in 2.3.15)
164 .BR MSG_CONFIRM " (since Linux 2.3.15)"
165 Tell the link layer that forward progress happened: you got a successful
166 reply from the other side.
167 If the link layer doesn't get this
168 it will regularly reprobe the neighbor (e.g., via a unicast ARP).
169 Valid only on
170 .B SOCK_DGRAM
172 .B SOCK_RAW
173 sockets and currently implemented only for IPv4 and IPv6.
175 .BR arp (7)
176 for details.
178 .B MSG_DONTROUTE
179 Don't use a gateway to send out the packet, send to hosts only on
180 directly connected networks.
181 This is usually used only
182 by diagnostic or routing programs.
183 This is defined only for protocol
184 families that route; packet sockets don't.
186 .BR MSG_DONTWAIT " (since Linux 2.2)"
187 Enables nonblocking operation; if the operation would block,
188 .B EAGAIN
190 .B EWOULDBLOCK
191 is returned.
192 This provides similar behavior to setting the
193 .B O_NONBLOCK
194 flag (via the
195 .BR fcntl (2)
196 .B F_SETFL
197 operation), but differs in that
198 .B MSG_DONTWAIT
199 is a per-call option, whereas
200 .B O_NONBLOCK
201 is a setting on the open file description (see
202 .BR open (2)),
203 which will affect all threads in the calling process
204 and as well as other processes that hold file descriptors
205 referring to the same open file description.
207 .BR MSG_EOR " (since Linux 2.2)"
208 Terminates a record (when this notion is supported, as for sockets of type
209 .BR SOCK_SEQPACKET ).
211 .BR MSG_MORE " (since Linux 2.4.4)"
212 The caller has more data to send.
213 This flag is used with TCP sockets to obtain the same effect
214 as the
215 .B TCP_CORK
216 socket option (see
217 .BR tcp (7)),
218 with the difference that this flag can be set on a per-call basis.
220 Since Linux 2.6, this flag is also supported for UDP sockets, and informs
221 the kernel to package all of the data sent in calls with this flag set
222 into a single datagram which is transmitted only when a call is performed
223 that does not specify this flag.
224 (See also the
225 .B UDP_CORK
226 socket option described in
227 .BR udp (7).)
229 .BR MSG_NOSIGNAL " (since Linux 2.2)"
230 Don't generate a
231 .B SIGPIPE
232 signal if the peer on a stream-oriented socket has closed the connection.
234 .B EPIPE
235 error is still returned.
236 This provides similar behavior to using
237 .BR sigaction (2)
238 to ignore
239 .BR SIGPIPE ,
240 but, whereas
241 .B MSG_NOSIGNAL
242 is a per-call feature,
243 ignoring
244 .B SIGPIPE
245 sets a process attribute that affects all threads in the process.
247 .B MSG_OOB
248 Sends
249 .I out-of-band
250 data on sockets that support this notion (e.g., of type
251 .BR SOCK_STREAM );
252 the underlying protocol must also support
253 .I out-of-band
254 data.
255 .SS sendmsg()
256 The definition of the
257 .I msghdr
258 structure employed by
259 .BR sendmsg ()
260 is as follows:
262 .in +4n
264 struct msghdr {
265     void         *msg_name;       /* Optional address */
266     socklen_t     msg_namelen;    /* Size of address */
267     struct iovec *msg_iov;        /* Scatter/gather array */
268     size_t        msg_iovlen;     /* # elements in msg_iov */
269     void         *msg_control;    /* Ancillary data, see below */
270     size_t        msg_controllen; /* Ancillary data buffer len */
271     int           msg_flags;      /* Flags (unused) */
277 .I msg_name
278 field is used on an unconnected socket to specify the target
279 address for a datagram.
280 It points to a buffer containing the address; the
281 .I msg_namelen
282 field should be set to the size of the address.
283 For a connected socket, these fields should be specified as NULL and 0,
284 respectively.
287 .I msg_iov
289 .I msg_iovlen
290 fields specify scatter-gather locations, as for
291 .BR writev (2).
293 You may send control information (ancillary data) using the
294 .I msg_control
296 .I msg_controllen
297 members.
298 The maximum control buffer length the kernel can process is limited
299 per socket by the value in
300 .IR /proc/sys/net/core/optmem_max ;
302 .BR socket (7).
303 For further information on the use of ancillary data in various
304 socket domains, see
305 .BR unix (7)
307 .BR ip (7).
310 .I msg_flags
311 field is ignored.
312 .\" Still to be documented:
313 .\"  Send file descriptors and user credentials using the
314 .\"  msg_control* fields.
315 .SH RETURN VALUE
316 On success, these calls return the number of bytes sent.
317 On error, \-1 is returned, and
318 .I errno
319 is set to indicate the error.
320 .SH ERRORS
321 These are some standard errors generated by the socket layer.
322 Additional errors
323 may be generated and returned from the underlying protocol modules;
324 see their respective manual pages.
326 .B EACCES
327 (For UNIX domain sockets, which are identified by pathname)
328 Write permission is denied on the destination socket file,
329 or search permission is denied for one of the directories
330 the path prefix.
331 (See
332 .BR path_resolution (7).)
334 (For UDP sockets) An attempt was made to send to a
335 network/broadcast address as though it was a unicast address.
337 .BR EAGAIN " or " EWOULDBLOCK
338 .\" Actually EAGAIN on Linux
339 The socket is marked nonblocking and the requested operation
340 would block.
341 POSIX.1-2001 allows either error to be returned for this case,
342 and does not require these constants to have the same value,
343 so a portable application should check for both possibilities.
345 .B EAGAIN
346 (Internet domain datagram sockets)
347 The socket referred to by
348 .I sockfd
349 had not previously been bound to an address and,
350 upon attempting to bind it to an ephemeral port,
351 it was determined that all port numbers in the ephemeral port range
352 are currently in use.
353 See the discussion of
354 .I /proc/sys/net/ipv4/ip_local_port_range
356 .BR ip (7).
358 .B EALREADY
359 Another Fast Open is in progress.
361 .B EBADF
362 .I sockfd
363 is not a valid open file descriptor.
365 .B ECONNRESET
366 Connection reset by peer.
368 .B EDESTADDRREQ
369 The socket is not connection-mode, and no peer address is set.
371 .B EFAULT
372 An invalid user space address was specified for an argument.
374 .B EINTR
375 A signal occurred before any data was transmitted; see
376 .BR signal (7).
378 .B EINVAL
379 Invalid argument passed.
381 .B EISCONN
382 The connection-mode socket was connected already but a
383 recipient was specified.
384 (Now either this error is returned, or the recipient specification
385 is ignored.)
387 .B EMSGSIZE
388 The socket type
389 .\" (e.g., SOCK_DGRAM )
390 requires that message be sent atomically, and the size
391 of the message to be sent made this impossible.
393 .B ENOBUFS
394 The output queue for a network interface was full.
395 This generally indicates that the interface has stopped sending,
396 but may be caused by transient congestion.
397 (Normally, this does not occur in Linux.
398 Packets are just silently dropped
399 when a device queue overflows.)
401 .B ENOMEM
402 No memory available.
404 .B ENOTCONN
405 The socket is not connected, and no target has been given.
407 .B ENOTSOCK
408 The file descriptor
409 .I sockfd
410 does not refer to a socket.
412 .B EOPNOTSUPP
413 Some bit in the
414 .I flags
415 argument is inappropriate for the socket type.
417 .B EPIPE
418 The local end has been shut down on a connection oriented socket.
419 In this case, the process
420 will also receive a
421 .B SIGPIPE
422 unless
423 .B MSG_NOSIGNAL
424 is set.
425 .SH CONFORMING TO
426 4.4BSD, SVr4, POSIX.1-2001.
427 These interfaces first appeared in 4.2BSD.
429 POSIX.1-2001 describes only the
430 .B MSG_OOB
432 .B MSG_EOR
433 flags.
434 POSIX.1-2008 adds a specification of
435 .BR MSG_NOSIGNAL .
437 .B MSG_CONFIRM
438 flag is a Linux extension.
439 .SH NOTES
440 According to POSIX.1-2001, the
441 .I msg_controllen
442 field of the
443 .I msghdr
444 structure should be typed as
445 .IR socklen_t ,
446 and the
447 .I msg_iovlen
448 field should be typed as
449 .IR int ,
450 but glibc currently types both as
451 .IR size_t .
452 .\" glibc bug for msg_controllen raised 12 Mar 2006
453 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
454 .\" The problem is an underlying kernel issue: the size of the
455 .\" __kernel_size_t type used to type these fields varies
456 .\" across architectures, but socklen_t is always 32 bits,
457 .\" as (at least with GCC) is int.
460 .BR sendmmsg (2)
461 for information about a Linux-specific system call
462 that can be used to transmit multiple datagrams in a single call.
463 .SH BUGS
464 Linux may return
465 .B EPIPE
466 instead of
467 .BR ENOTCONN .
468 .SH EXAMPLES
469 An example of the use of
470 .BR sendto ()
471 is shown in
472 .BR getaddrinfo (3).
473 .SH SEE ALSO
474 .BR fcntl (2),
475 .BR getsockopt (2),
476 .BR recv (2),
477 .BR select (2),
478 .BR sendfile (2),
479 .BR sendmmsg (2),
480 .BR shutdown (2),
481 .BR socket (2),
482 .BR write (2),
483 .BR cmsg (3),
484 .BR ip (7),
485 .BR ipv6 (7),
486 .BR socket (7),
487 .BR tcp (7),
488 .BR udp (7),
489 .BR unix (7)