man2/send.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   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 .\"
  12 .TH send 2 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 send, sendto, sendmsg \- send a message on a socket
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <sys/socket.h>
  21 .P
  22 .BI "ssize_t send(int " sockfd ", const void " buf [. len "], size_t " len \
  23 ", int " flags );
  24 .BI "ssize_t sendto(int " sockfd ", const void " buf [. len "], size_t " len \
  25 ", int " flags ,
  26 .BI "               const struct sockaddr *" dest_addr ", socklen_t " addrlen );
  27 .BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \
  28 ", int " flags );
  29 .fi
  30 .SH DESCRIPTION
  31 The system calls
  32 .BR send (),
  33 .BR sendto (),
  34 and
  35 .BR sendmsg ()
  36 are used to transmit a message to another socket.
  37 .P
  38 The
  39 .BR send ()
  40 call may be used only when the socket is in a
  41 .I connected
  42 state (so that the intended recipient is known).
  43 The only difference between
  44 .BR send ()
  45 and
  46 .BR write (2)
  47 is the presence of
  48 .IR flags .
  49 With a zero
  50 .I flags
  51 argument,
  52 .BR send ()
  53 is equivalent to
  54 .BR write (2).
  55 Also, the following call
  56 .P
  57 .in +4n
  58 .EX
  59 send(sockfd, buf, len, flags);
  60 .EE
  61 .in
  62 .P
  63 is equivalent to
  64 .P
  65 .in +4n
  66 .EX
  67 sendto(sockfd, buf, len, flags, NULL, 0);
  68 .EE
  69 .in
  70 .P
  71 The argument
  72 .I sockfd
  73 is the file descriptor of the sending socket.
  74 .P
  75 If
  76 .BR sendto ()
  77 is used on a connection-mode
  78 .RB ( SOCK_STREAM ,
  79 .BR SOCK_SEQPACKET )
  80 socket, the arguments
  81 .I dest_addr
  82 and
  83 .I addrlen
  84 are ignored (and the error
  85 .B EISCONN
  86 may be returned when they are
  87 not NULL and 0), and the error
  88 .B ENOTCONN
  89 is returned when the socket was not actually connected.
  90 Otherwise, the address of the target is given by
  91 .I dest_addr
  92 with
  93 .I addrlen
  94 specifying its size.
  95 For
  96 .BR sendmsg (),
  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 .P
 103 For
 104 .BR send ()
 105 and
 106 .BR sendto (),
 107 the message is found in
 108 .I buf
 109 and has length
 110 .IR len .
 111 For
 112 .BR sendmsg (),
 113 the message is pointed to by the elements of the array
 114 .IR msg.msg_iov .
 115 The
 116 .BR sendmsg ()
 117 call also allows sending ancillary data (also known as control information).
 118 .P
 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 .P
 124 No indication of failure to deliver is implicit in a
 125 .BR send ().
 126 Locally detected errors are indicated by a return value of \-1.
 127 .P
 128 When the message does not fit into the send buffer of the socket,
 129 .BR send ()
 130 normally blocks, unless the socket has been placed in nonblocking I/O
 131 mode.
 132 In nonblocking mode it would fail with the error
 133 .B EAGAIN
 134 or
 135 .B EWOULDBLOCK
 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.
 140 .SS The flags argument
 141 The
 142 .I flags
 143 argument is the bitwise OR
 144 of zero or more of the following flags.
 145 .\" FIXME . ? document MSG_PROXY (which went away in Linux 2.3.15)
 146 .TP
 147 .BR MSG_CONFIRM " (since Linux 2.3.15)"
 148 Tell the link layer that forward progress happened: you got a successful
 149 reply from the other side.
 150 If the link layer doesn't get this
 151 it will regularly reprobe the neighbor (e.g., via a unicast ARP).
 152 Valid only on
 153 .B SOCK_DGRAM
 154 and
 155 .B SOCK_RAW
 156 sockets and currently implemented only for IPv4 and IPv6.
 157 See
 158 .BR arp (7)
 159 for details.
 160 .TP
 161 .B MSG_DONTROUTE
 162 Don't use a gateway to send out the packet, send to hosts only on
 163 directly connected networks.
 164 This is usually used only
 165 by diagnostic or routing programs.
 166 This is defined only for protocol
 167 families that route; packet sockets don't.
 168 .TP
 169 .BR MSG_DONTWAIT " (since Linux 2.2)"
 170 Enables nonblocking operation; if the operation would block,
 171 .B EAGAIN
 172 or
 173 .B EWOULDBLOCK
 174 is returned.
 175 This provides similar behavior to setting the
 176 .B O_NONBLOCK
 177 flag (via the
 178 .BR fcntl (2)
 179 .B F_SETFL
 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 as well as other processes that hold file descriptors
 188 referring to the same open file description.
 189 .TP
 190 .BR MSG_EOR " (since Linux 2.2)"
 191 Terminates a record (when this notion is supported, as for sockets of type
 192 .BR SOCK_SEQPACKET ).
 193 .TP
 194 .BR MSG_MORE " (since Linux 2.4.4)"
 195 The caller has more data to send.
 196 This flag is used with TCP sockets to obtain the same effect
 197 as the
 198 .B TCP_CORK
 199 socket option (see
 200 .BR tcp (7)),
 201 with the difference that this flag can be set on a per-call basis.
 202 .IP
 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
 205 into a single datagram which is transmitted only when a call is performed
 206 that does not specify this flag.
 207 (See also the
 208 .B UDP_CORK
 209 socket option described in
 210 .BR udp (7).)
 211 .TP
 212 .BR MSG_NOSIGNAL " (since Linux 2.2)"
 213 Don't generate a
 214 .B SIGPIPE
 215 signal if the peer on a stream-oriented socket has closed the connection.
 216 The
 217 .B EPIPE
 218 error is still returned.
 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.
 229 .TP
 230 .B MSG_OOB
 231 Sends
 232 .I out-of-band
 233 data on sockets that support this notion (e.g., of type
 234 .BR SOCK_STREAM );
 235 the underlying protocol must also support
 236 .I out-of-band
 237 data.
 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.
 270 .SS sendmsg()
 271 The definition of the
 272 .I msghdr
 273 structure employed by
 274 .BR sendmsg ()
 275 is as follows:
 276 .P
 277 .in +4n
 278 .EX
 279 struct msghdr {
 280     void         *msg_name;       /* Optional address */
 281     socklen_t     msg_namelen;    /* Size of address */
 282     struct iovec *msg_iov;        /* Scatter/gather array */
 283     size_t        msg_iovlen;     /* # elements in msg_iov */
 284     void         *msg_control;    /* Ancillary data, see below */
 285     size_t        msg_controllen; /* Ancillary data buffer len */
 286     int           msg_flags;      /* Flags (unused) */
 287 };
 288 .EE
 289 .in
 290 .P
 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
 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 length 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; see
 391 .BR signal (7).
 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.
 412 (Normally, this does not occur in Linux.
 413 Packets are just silently dropped
 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
 423 The file descriptor
 424 .I sockfd
 425 does not refer to a socket.
 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.
 434 In this case, the process
 435 will also receive a
 436 .B SIGPIPE
 437 unless
 438 .B MSG_NOSIGNAL
 439 is set.
 440 .SH VERSIONS
 441 According to POSIX.1-2001, the
 442 .I msg_controllen
 443 field of the
 444 .I msghdr
 445 structure should be typed as
 446 .IR socklen_t ,
 447 and the
 448 .I msg_iovlen
 449 field should be typed as
 450 .IR int ,
 451 but glibc currently types both as
 452 .IR size_t .
 453 .\" glibc bug for msg_controllen raised 12 Mar 2006
 454 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 455 .\" The problem is an underlying kernel issue: the size of the
 456 .\" __kernel_size_t type used to type these fields varies
 457 .\" across architectures, but socklen_t is always 32 bits,
 458 .\" as (at least with GCC) is int.
 459 .SH STANDARDS
 460 POSIX.1-2008.
 461 .P
 462 .B MSG_CONFIRM
 463 is a Linux extension.
 464 .SH HISTORY
 465 4.4BSD, SVr4, POSIX.1-2001.
 466 (first appeared in 4.2BSD).
 467 .P
 468 POSIX.1-2001 describes only the
 469 .B MSG_OOB
 470 and
 471 .B MSG_EOR
 472 flags.
 473 POSIX.1-2008 adds a specification of
 474 .BR MSG_NOSIGNAL .
 475 .SH NOTES
 476 See
 477 .BR sendmmsg (2)
 478 for information about a Linux-specific system call
 479 that can be used to transmit multiple datagrams in a single call.
 480 .SH BUGS
 481 Linux may return
 482 .B EPIPE
 483 instead of
 484 .BR ENOTCONN .
 485 .SH EXAMPLES
 486 An example of the use of
 487 .BR sendto ()
 488 is shown in
 489 .BR getaddrinfo (3).
 490 .SH SEE ALSO
 491 .BR fcntl (2),
 492 .BR getsockopt (2),
 493 .BR recv (2),
 494 .BR select (2),
 495 .BR sendfile (2),
 496 .BR sendmmsg (2),
 497 .BR shutdown (2),
 498 .BR socket (2),
 499 .BR write (2),
 500 .BR cmsg (3),
 501 .BR ip (7),
 502 .BR ipv6 (7),
 503 .BR socket (7),
 504 .BR tcp (7),
 505 .BR udp (7),
 506 .BR unix (7)