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