man2/send.2

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