| 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) |