]>
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 | .\" | |
4c49bf90 | 40 | .TH SEND 2 2012-04-23 "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. | |
160 | .PP | |
161 | The | |
162 | .I flags | |
c4bb193f | 163 | argument is the bitwise OR |
fea681da | 164 | of zero or more of the following flags. |
0e1ad98c | 165 | .\" FIXME ? document MSG_PROXY (which went away in 2.3.15) |
fea681da | 166 | .TP |
2dd5352d | 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). |
c13182ef | 172 | Only valid on |
a28ed21c MK |
173 | .B SOCK_DGRAM |
174 | and | |
175 | .B SOCK_RAW | |
c13182ef MK |
176 | sockets and currently only implemented for IPv4 and IPv6. |
177 | See | |
a28ed21c MK |
178 | .BR arp (7) |
179 | for details. | |
fea681da MK |
180 | .TP |
181 | .B MSG_DONTROUTE | |
c13182ef MK |
182 | Don't use a gateway to send out the packet, only send to hosts on |
183 | directly connected networks. | |
184 | This is usually used only | |
185 | by diagnostic or routing programs. | |
186 | This is only defined 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 | |
fea681da MK |
194 | is returned (this can also be enabled using the |
195 | .B O_NONBLOCK | |
86426e0b | 196 | flag with the |
fea681da MK |
197 | .B F_SETFL |
198 | .BR fcntl (2)). | |
199 | .TP | |
6eb4bccc | 200 | .BR MSG_EOR " (since Linux 2.2)" |
a28ed21c MK |
201 | Terminates a record (when this notion is supported, as for sockets of type |
202 | .BR SOCK_SEQPACKET ). | |
fea681da MK |
203 | .TP |
204 | .BR MSG_MORE " (Since Linux 2.4.4)" | |
205 | The caller has more data to send. | |
206 | This flag is used with TCP sockets to obtain the same effect | |
2f0af33b MK |
207 | as the |
208 | .B TCP_CORK | |
209 | socket option (see | |
fea681da MK |
210 | .BR tcp (7)), |
211 | with the difference that this flag can be set on a per-call basis. | |
ca92ce95 | 212 | |
fea681da MK |
213 | Since Linux 2.6, this flag is also supported for UDP sockets, and informs |
214 | the kernel to package all of the data sent in calls with this flag set | |
215 | into a single datagram which is only transmitted when a call is performed | |
c13182ef MK |
216 | that does not specify this flag. |
217 | (See also the | |
218 | .B UDP_CORK | |
219 | socket option described in | |
145ff024 | 220 | .BR udp (7).) |
a28ed21c | 221 | .TP |
6eb4bccc | 222 | .BR MSG_NOSIGNAL " (since Linux 2.2)" |
c13182ef MK |
223 | Requests not to send |
224 | .B SIGPIPE | |
a28ed21c | 225 | on errors on stream oriented sockets when the other end breaks the |
c13182ef MK |
226 | connection. |
227 | The | |
a28ed21c MK |
228 | .B EPIPE |
229 | error is still returned. | |
230 | .TP | |
231 | .B MSG_OOB | |
232 | Sends | |
233 | .I out-of-band | |
75b94dc3 | 234 | data on sockets that support this notion (e.g., of type |
a28ed21c MK |
235 | .BR SOCK_STREAM ); |
236 | the underlying protocol must also support | |
237 | .I out-of-band | |
238 | data. | |
fea681da MK |
239 | .PP |
240 | The definition of the | |
241 | .I msghdr | |
c13182ef MK |
242 | structure follows. |
243 | See | |
fea681da MK |
244 | .BR recv (2) |
245 | and below for an exact description of its fields. | |
a08ea57c | 246 | .in +4n |
fea681da | 247 | .nf |
ea4adf4b | 248 | |
fea681da | 249 | struct msghdr { |
ea4adf4b MK |
250 | void *msg_name; /* optional address */ |
251 | socklen_t msg_namelen; /* size of address */ | |
252 | struct iovec *msg_iov; /* scatter/gather array */ | |
253 | size_t msg_iovlen; /* # elements in msg_iov */ | |
254 | void *msg_control; /* ancillary data, see below */ | |
f07435fb | 255 | size_t msg_controllen; /* ancillary data buffer len */ |
ea4adf4b | 256 | int msg_flags; /* flags on received message */ |
fea681da | 257 | }; |
fea681da | 258 | .fi |
a08ea57c | 259 | .in |
fea681da | 260 | .PP |
c13182ef MK |
261 | You may send control information using the |
262 | .I msg_control | |
263 | and | |
264 | .I msg_controllen | |
265 | members. | |
266 | The maximum control buffer length the kernel can process is limited | |
5a2ff571 MK |
267 | per socket by the value in |
268 | .IR /proc/sys/net/core/optmem_max ; | |
269 | see | |
fea681da MK |
270 | .BR socket (7). |
271 | .\" Still to be documented: | |
272 | .\" Send file descriptors and user credentials using the | |
273 | .\" msg_control* fields. | |
274 | .\" The flags returned in msg_flags. | |
47297adb | 275 | .SH RETURN VALUE |
cca657e2 MK |
276 | On success, these calls return the number of characters sent. |
277 | On error, \-1 is returned, and | |
278 | .I errno | |
279 | is set appropriately. | |
fea681da | 280 | .SH ERRORS |
c13182ef MK |
281 | These are some standard errors generated by the socket layer. |
282 | Additional errors | |
283 | may be generated and returned from the underlying protocol modules; | |
284 | see their respective manual pages. | |
fea681da MK |
285 | .TP |
286 | .B EACCES | |
008f1ecc | 287 | (For UNIX domain sockets, which are identified by pathname) |
fea681da MK |
288 | Write permission is denied on the destination socket file, |
289 | or search permission is denied for one of the directories | |
c13182ef MK |
290 | the path prefix. |
291 | (See | |
ad7cc990 | 292 | .BR path_resolution (7).) |
4c49bf90 SP |
293 | .sp |
294 | (For UDP sockets) An attempt was made to send to a | |
295 | network/broadcast address as though it was a unicast address. | |
fea681da MK |
296 | .TP |
297 | .BR EAGAIN " or " EWOULDBLOCK | |
86426e0b | 298 | .\" Actually EAGAIN on Linux |
ff40dbb3 | 299 | The socket is marked nonblocking and the requested operation |
fea681da | 300 | would block. |
86426e0b MK |
301 | POSIX.1-2001 allows either error to be returned for this case, |
302 | and does not require these constants to have the same value, | |
303 | so a portable application should check for both possibilities. | |
fea681da MK |
304 | .TP |
305 | .B EBADF | |
306 | An invalid descriptor was specified. | |
307 | .TP | |
308 | .B ECONNRESET | |
309 | Connection reset by peer. | |
310 | .TP | |
311 | .B EDESTADDRREQ | |
312 | The socket is not connection-mode, and no peer address is set. | |
313 | .TP | |
314 | .B EFAULT | |
c4bb193f | 315 | An invalid user space address was specified for an argument. |
fea681da MK |
316 | .TP |
317 | .B EINTR | |
01538d0d MK |
318 | A signal occurred before any data was transmitted; see |
319 | .BR signal (7). | |
fea681da MK |
320 | .TP |
321 | .B EINVAL | |
322 | Invalid argument passed. | |
323 | .TP | |
324 | .B EISCONN | |
325 | The connection-mode socket was connected already but a | |
326 | recipient was specified. | |
327 | (Now either this error is returned, or the recipient specification | |
328 | is ignored.) | |
329 | .TP | |
330 | .B EMSGSIZE | |
331 | The socket type | |
332 | .\" (e.g., SOCK_DGRAM ) | |
333 | requires that message be sent atomically, and the size | |
334 | of the message to be sent made this impossible. | |
335 | .TP | |
336 | .B ENOBUFS | |
337 | The output queue for a network interface was full. | |
338 | This generally indicates that the interface has stopped sending, | |
339 | but may be caused by transient congestion. | |
c13182ef MK |
340 | (Normally, this does not occur in Linux. |
341 | Packets are just silently dropped | |
fea681da MK |
342 | when a device queue overflows.) |
343 | .TP | |
344 | .B ENOMEM | |
345 | No memory available. | |
346 | .TP | |
347 | .B ENOTCONN | |
348 | The socket is not connected, and no target has been given. | |
349 | .TP | |
350 | .B ENOTSOCK | |
351 | The argument | |
3e4088f4 | 352 | .I sockfd |
fea681da MK |
353 | is not a socket. |
354 | .TP | |
355 | .B EOPNOTSUPP | |
356 | Some bit in the | |
357 | .I flags | |
358 | argument is inappropriate for the socket type. | |
359 | .TP | |
360 | .B EPIPE | |
361 | The local end has been shut down on a connection oriented socket. | |
362 | In this case the process | |
c13182ef MK |
363 | will also receive a |
364 | .B SIGPIPE | |
365 | unless | |
366 | .B MSG_NOSIGNAL | |
fea681da | 367 | is set. |
47297adb | 368 | .SH CONFORMING TO |
97c1eac8 | 369 | 4.4BSD, SVr4, POSIX.1-2001. |
fea681da MK |
370 | These function calls appeared in 4.2BSD. |
371 | .LP | |
97c1eac8 | 372 | POSIX.1-2001 only describes the |
fea681da MK |
373 | .B MSG_OOB |
374 | and | |
375 | .B MSG_EOR | |
376 | flags. | |
e5ded49f MK |
377 | POSIX.1-2008 adds a specification of |
378 | .BR MSG_NOSIGNAL . | |
fea681da | 379 | The |
c13182ef | 380 | .B MSG_CONFIRM |
fea681da | 381 | flag is a Linux extension. |
ea4adf4b | 382 | .SH NOTES |
008f1ecc | 383 | The prototypes given above follow the Single UNIX Specification, |
fea681da MK |
384 | as glibc2 also does; the |
385 | .I flags | |
2b0fa182 | 386 | argument was \fIint\fP in 4.x BSD, but \fIunsigned int\fP in libc4 and libc5; |
fea681da MK |
387 | the |
388 | .I len | |
2b0fa182 | 389 | argument was \fIint\fP in 4.x BSD and libc4, but \fIsize_t\fP in libc5; |
fea681da | 390 | the |
6926dbf5 | 391 | .I addrlen |
2b0fa182 | 392 | argument was \fIint\fP in 4.x BSD and libc4 and libc5. |
fea681da MK |
393 | See also |
394 | .BR accept (2). | |
ea4adf4b MK |
395 | |
396 | According to POSIX.1-2001, the | |
397 | .I msg_controllen | |
398 | field of the | |
399 | .I msghdr | |
400 | structure should be typed as | |
401 | .IR socklen_t , | |
b637ad73 | 402 | but glibc currently types it as |
ea4adf4b | 403 | .IR size_t . |
1c511da2 | 404 | .\" glibc bug raised 12 Mar 2006 |
ea4adf4b | 405 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 |
1c511da2 MK |
406 | .\" The problem is an underlying kernel issue: the size of the |
407 | .\" __kernel_size_t type used to type this field varies | |
408 | .\" across architectures, but socklen_t is always 32 bits. | |
53aeb9c2 MK |
409 | |
410 | See | |
6fdbc779 | 411 | .BR sendmmsg (2) |
53aeb9c2 MK |
412 | for information about a Linux-specific system call |
413 | that can be used to transmit multiple datagrams in a single call. | |
fea681da | 414 | .SH BUGS |
1274071a MK |
415 | Linux may return |
416 | .B EPIPE | |
2f0af33b MK |
417 | instead of |
418 | .BR ENOTCONN . | |
1c27853f MK |
419 | .SH EXAMPLE |
420 | An example of the use of | |
421 | .BR sendto () | |
422 | is shown in | |
423 | .BR getaddrinfo (3). | |
47297adb | 424 | .SH SEE ALSO |
fea681da MK |
425 | .BR fcntl (2), |
426 | .BR getsockopt (2), | |
427 | .BR recv (2), | |
428 | .BR select (2), | |
429 | .BR sendfile (2), | |
53aeb9c2 | 430 | .BR sendmmsg (2), |
85a3dc20 | 431 | .BR shutdown (2), |
fea681da MK |
432 | .BR socket (2), |
433 | .BR write (2), | |
1df419f2 | 434 | .BR cmsg (3), |
fea681da MK |
435 | .BR ip (7), |
436 | .BR socket (7), | |
437 | .BR tcp (7), | |
438 | .BR udp (7) |