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 2017-09-15 "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/types.h>
  46 .B #include <sys/socket.h>
  47 .PP
  48 .BI "ssize_t send(int " sockfd ", const void *" buf ", size_t " len \
  49 ", int " flags );
  50 .PP
  51 .BI "ssize_t sendto(int " sockfd ", const void *" buf ", size_t " len \
  52 ", int " flags ,
  53 .BI "               const struct sockaddr *" dest_addr ", socklen_t " addrlen );
  54 .PP
  55 .BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \
  56 ", int " flags );
  57 .fi
  58 .SH DESCRIPTION
  59 The system calls
  60 .BR send (),
  61 .BR sendto (),
  62 and
  63 .BR sendmsg ()
  64 are used to transmit a message to another socket.
  65 .PP
  66 The
  67 .BR send ()
  68 call may be used only when the socket is in a
  69 .I connected
  70 state (so that the intended recipient is known).
  71 The only difference between
  72 .BR send ()
  73 and
  74 .BR write (2)
  75 is the presence of
  76 .IR flags .
  77 With a zero
  78 .I flags
  79 argument,
  80 .BR send ()
  81 is equivalent to
  82 .BR write (2).
  83 Also, the following call
  84 .PP
  85     send(sockfd, buf, len, flags);
  86 .PP
  87 is equivalent to
  88 .PP
  89     sendto(sockfd, buf, len, flags, NULL, 0);
  90 .PP
  91 The argument
  92 .I sockfd
  93 is the file descriptor of the sending socket.
  94 .PP
  95 If
  96 .BR sendto ()
  97 is used on a connection-mode
  98 .RB ( SOCK_STREAM ,
  99 .BR SOCK_SEQPACKET )
 100 socket, the arguments
 101 .I dest_addr
 102 and
 103 .I addrlen
 104 are ignored (and the error
 105 .B EISCONN
 106 may be returned when they are
 107 not NULL and 0), and the error
 108 .B ENOTCONN
 109 is returned when the socket was not actually connected.
 110 Otherwise, the address of the target is given by
 111 .I dest_addr
 112 with
 113 .I addrlen
 114 specifying its size.
 115 For
 116 .BR sendmsg (),
 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
 124 .BR send ()
 125 and
 126 .BR sendto (),
 127 the message is found in
 128 .I buf
 129 and has length
 130 .IR len .
 131 For
 132 .BR sendmsg (),
 133 the message is pointed to by the elements of the array
 134 .IR msg.msg_iov .
 135 The
 136 .BR sendmsg ()
 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
 145 .BR send ().
 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,
 149 .BR send ()
 150 normally blocks, unless the socket has been placed in nonblocking I/O
 151 mode.
 152 In nonblocking mode it would fail with the error
 153 .B EAGAIN
 154 or
 155 .B EWOULDBLOCK
 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 .SS The flags argument
 161 The
 162 .I flags
 163 argument is the bitwise OR
 164 of zero or more of the following flags.
 165 .\" FIXME . ? document MSG_PROXY (which went away in 2.3.15)
 166 .TP
 167 .BR MSG_CONFIRM " (since Linux 2.3.15)"
 168 Tell the link layer that forward progress happened: you got a successful
 169 reply from the other side.
 170 If the link layer doesn't get this
 171 it will regularly reprobe the neighbor (e.g., via a unicast ARP).
 172 Valid only on
 173 .B SOCK_DGRAM
 174 and
 175 .B SOCK_RAW
 176 sockets and currently implemented only for IPv4 and IPv6.
 177 See
 178 .BR arp (7)
 179 for details.
 180 .TP
 181 .B MSG_DONTROUTE
 182 Don't use a gateway to send out the packet, send to hosts only on
 183 directly connected networks.
 184 This is usually used only
 185 by diagnostic or routing programs.
 186 This is defined only for protocol
 187 families that route; packet sockets don't.
 188 .TP
 189 .BR MSG_DONTWAIT " (since Linux 2.2)"
 190 Enables nonblocking operation; if the operation would block,
 191 .B EAGAIN
 192 or
 193 .B EWOULDBLOCK
 194 is returned.
 195 This provides similar behavior to setting the
 196 .B O_NONBLOCK
 197 flag (via the
 198 .BR fcntl (2)
 199 .B F_SETFL
 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.
 209 .TP
 210 .BR MSG_EOR " (since Linux 2.2)"
 211 Terminates a record (when this notion is supported, as for sockets of type
 212 .BR SOCK_SEQPACKET ).
 213 .TP
 214 .BR MSG_MORE " (since Linux 2.4.4)"
 215 The caller has more data to send.
 216 This flag is used with TCP sockets to obtain the same effect
 217 as the
 218 .B TCP_CORK
 219 socket option (see
 220 .BR tcp (7)),
 221 with the difference that this flag can be set on a per-call basis.
 222 .IP
 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
 225 into a single datagram which is transmitted only when a call is performed
 226 that does not specify this flag.
 227 (See also the
 228 .B UDP_CORK
 229 socket option described in
 230 .BR udp (7).)
 231 .TP
 232 .BR MSG_NOSIGNAL " (since Linux 2.2)"
 233 Don't generate a
 234 .B SIGPIPE
 235 signal if the peer on a stream-oriented socket has closed the connection.
 236 The
 237 .B EPIPE
 238 error is still returned.
 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.
 249 .TP
 250 .B MSG_OOB
 251 Sends
 252 .I out-of-band
 253 data on sockets that support this notion (e.g., of type
 254 .BR SOCK_STREAM );
 255 the underlying protocol must also support
 256 .I out-of-band
 257 data.
 258 .SS sendmsg()
 259 The definition of the
 260 .I msghdr
 261 structure employed by
 262 .BR sendmsg ()
 263 is as follows:
 264 .PP
 265 .in +4n
 266 .EX
 267 struct msghdr {
 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 */
 273     size_t        msg_controllen; /* Ancillary data buffer len */
 274     int           msg_flags;      /* Flags (unused) */
 275 };
 276 .EE
 277 .in
 278 .PP
 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
 284 .I msg_namelen
 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 .PP
 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 .PP
 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
 302 per socket by the value in
 303 .IR /proc/sys/net/core/optmem_max ;
 304 see
 305 .BR socket (7).
 306 .PP
 307 The
 308 .I msg_flags
 309 field is ignored.
 310 .\" Still to be documented:
 311 .\"  Send file descriptors and user credentials using the
 312 .\"  msg_control* fields.
 313 .SH RETURN VALUE
 314 On success, these calls return the number of bytes sent.
 315 On error, \-1 is returned, and
 316 .I errno
 317 is set appropriately.
 318 .SH ERRORS
 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.
 323 .TP
 324 .B EACCES
 325 (For UNIX domain sockets, which are identified by pathname)
 326 Write permission is denied on the destination socket file,
 327 or search permission is denied for one of the directories
 328 the path prefix.
 329 (See
 330 .BR path_resolution (7).)
 331 .IP
 332 (For UDP sockets) An attempt was made to send to a
 333 network/broadcast address as though it was a unicast address.
 334 .TP
 335 .BR EAGAIN " or " EWOULDBLOCK
 336 .\" Actually EAGAIN on Linux
 337 The socket is marked nonblocking and the requested operation
 338 would block.
 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.
 342 .TP
 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
 356 .B EALREADY
 357 Another Fast Open is in progress.
 358 .TP
 359 .B EBADF
 360 .I sockfd
 361 is not a valid open file descriptor.
 362 .TP
 363 .B ECONNRESET
 364 Connection reset by peer.
 365 .TP
 366 .B EDESTADDRREQ
 367 The socket is not connection-mode, and no peer address is set.
 368 .TP
 369 .B EFAULT
 370 An invalid user space address was specified for an argument.
 371 .TP
 372 .B EINTR
 373 A signal occurred before any data was transmitted; see
 374 .BR signal (7).
 375 .TP
 376 .B EINVAL
 377 Invalid argument passed.
 378 .TP
 379 .B EISCONN
 380 The connection-mode socket was connected already but a
 381 recipient was specified.
 382 (Now either this error is returned, or the recipient specification
 383 is ignored.)
 384 .TP
 385 .B EMSGSIZE
 386 The socket type
 387 .\" (e.g., SOCK_DGRAM )
 388 requires that message be sent atomically, and the size
 389 of the message to be sent made this impossible.
 390 .TP
 391 .B ENOBUFS
 392 The output queue for a network interface was full.
 393 This generally indicates that the interface has stopped sending,
 394 but may be caused by transient congestion.
 395 (Normally, this does not occur in Linux.
 396 Packets are just silently dropped
 397 when a device queue overflows.)
 398 .TP
 399 .B ENOMEM
 400 No memory available.
 401 .TP
 402 .B ENOTCONN
 403 The socket is not connected, and no target has been given.
 404 .TP
 405 .B ENOTSOCK
 406 The file descriptor
 407 .I sockfd
 408 does not refer to a socket.
 409 .TP
 410 .B EOPNOTSUPP
 411 Some bit in the
 412 .I flags
 413 argument is inappropriate for the socket type.
 414 .TP
 415 .B EPIPE
 416 The local end has been shut down on a connection oriented socket.
 417 In this case, the process
 418 will also receive a
 419 .B SIGPIPE
 420 unless
 421 .B MSG_NOSIGNAL
 422 is set.
 423 .SH CONFORMING TO
 424 4.4BSD, SVr4, POSIX.1-2001.
 425 These interfaces first appeared in 4.2BSD.
 426 .PP
 427 POSIX.1-2001 describes only the
 428 .B MSG_OOB
 429 and
 430 .B MSG_EOR
 431 flags.
 432 POSIX.1-2008 adds a specification of
 433 .BR MSG_NOSIGNAL .
 434 The
 435 .B MSG_CONFIRM
 436 flag is a Linux extension.
 437 .SH NOTES
 438 According to POSIX.1-2001, the
 439 .I msg_controllen
 440 field of the
 441 .I msghdr
 442 structure should be typed as
 443 .IR socklen_t ,
 444 but glibc currently types it as
 445 .IR size_t .
 446 .\" glibc bug raised 12 Mar 2006
 447 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 448 .\" The problem is an underlying kernel issue: the size of the
 449 .\" __kernel_size_t type used to type this field varies
 450 .\" across architectures, but socklen_t is always 32 bits.
 451 .PP
 452 See
 453 .BR sendmmsg (2)
 454 for information about a Linux-specific system call
 455 that can be used to transmit multiple datagrams in a single call.
 456 .SH BUGS
 457 Linux may return
 458 .B EPIPE
 459 instead of
 460 .BR ENOTCONN .
 461 .SH EXAMPLE
 462 An example of the use of
 463 .BR sendto ()
 464 is shown in
 465 .BR getaddrinfo (3).
 466 .SH SEE ALSO
 467 .BR fcntl (2),
 468 .BR getsockopt (2),
 469 .BR recv (2),
 470 .BR select (2),
 471 .BR sendfile (2),
 472 .BR sendmmsg (2),
 473 .BR shutdown (2),
 474 .BR socket (2),
 475 .BR write (2),
 476 .BR cmsg (3),
 477 .BR ip (7),
 478 .BR ipv6 (7),
 479 .BR socket (7),
 480 .BR tcp (7),
 481 .BR udp (7),
 482 .BR unix (7)