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