original/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 2014-08-19 "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 .sp
  48 .BI "ssize_t send(int " sockfd ", const void *" buf ", size_t " len \
  49 ", int " flags );
  50
  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
  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
  85     send(sockfd, buf, len, flags);
  86
  87 is equivalent to
  88
  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 Only valid 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 (this can also be enabled using the
 195 .B O_NONBLOCK
 196 flag with the
 197 .B F_SETFL
 198 .BR fcntl (2)).
 199 .TP
 200 .BR MSG_EOR " (since Linux 2.2)"
 201 Terminates a record (when this notion is supported, as for sockets of type
 202 .BR SOCK_SEQPACKET ).
 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
 207 as the
 208 .B TCP_CORK
 209 socket option (see
 210 .BR tcp (7)),
 211 with the difference that this flag can be set on a per-call basis.
 212
 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 transmitted only when a call is performed
 216 that does not specify this flag.
 217 (See also the
 218 .B UDP_CORK
 219 socket option described in
 220 .BR udp (7).)
 221 .TP
 222 .BR MSG_NOSIGNAL " (since Linux 2.2)"
 223 Requests not to send
 224 .B SIGPIPE
 225 on errors on stream oriented sockets when the other end breaks the
 226 connection.
 227 The
 228 .B EPIPE
 229 error is still returned.
 230 .TP
 231 .B MSG_OOB
 232 Sends
 233 .I out-of-band
 234 data on sockets that support this notion (e.g., of type
 235 .BR SOCK_STREAM );
 236 the underlying protocol must also support
 237 .I out-of-band
 238 data.
 239 .SS sendmsg()
 240 The definition of the
 241 .I msghdr
 242 structure employed by
 243 .BR sendmsg ()
 244 is as follows:
 245 .in +4n
 246 .nf
 247
 248 struct msghdr {
 249     void         *msg_name;       /* optional address */
 250     socklen_t     msg_namelen;    /* size of address */
 251     struct iovec *msg_iov;        /* scatter/gather array */
 252     size_t        msg_iovlen;     /* # elements in msg_iov */
 253     void         *msg_control;    /* ancillary data, see below */
 254     size_t        msg_controllen; /* ancillary data buffer len */
 255     int           msg_flags;      /* flags (unused) */
 256 };
 257 .fi
 258 .in
 259 .PP
 260 The
 261 .I msg_name
 262 field is used on an unconnected socket to specify the target
 263 address for a datagram.
 264 It points to a buffer containing the address; the
 265 .I msg_namelen
 266 field should be set to the size of the address.
 267 For a connected socket, these fields should be specified as NULL and 0,
 268 respectively.
 269
 270 The
 271 .I msg_iov
 272 and
 273 .I msg_iovlen
 274 fields specify scatter-gather locations, as for
 275 .BR writev (2).
 276
 277 You may send control information using the
 278 .I msg_control
 279 and
 280 .I msg_controllen
 281 members.
 282 The maximum control buffer length the kernel can process is limited
 283 per socket by the value in
 284 .IR /proc/sys/net/core/optmem_max ;
 285 see
 286 .BR socket (7).
 287
 288 The
 289 .I msg_flags
 290 field is ignored.
 291 .\" Still to be documented:
 292 .\"  Send file descriptors and user credentials using the
 293 .\"  msg_control* fields.
 294 .SH RETURN VALUE
 295 On success, these calls return the number of bytes sent.
 296 On error, \-1 is returned, and
 297 .I errno
 298 is set appropriately.
 299 .SH ERRORS
 300 These are some standard errors generated by the socket layer.
 301 Additional errors
 302 may be generated and returned from the underlying protocol modules;
 303 see their respective manual pages.
 304 .TP
 305 .B EACCES
 306 (For UNIX domain sockets, which are identified by pathname)
 307 Write permission is denied on the destination socket file,
 308 or search permission is denied for one of the directories
 309 the path prefix.
 310 (See
 311 .BR path_resolution (7).)
 312 .sp
 313 (For UDP sockets) An attempt was made to send to a
 314 network/broadcast address as though it was a unicast address.
 315 .TP
 316 .BR EAGAIN " or " EWOULDBLOCK
 317 .\" Actually EAGAIN on Linux
 318 The socket is marked nonblocking and the requested operation
 319 would block.
 320 POSIX.1-2001 allows either error to be returned for this case,
 321 and does not require these constants to have the same value,
 322 so a portable application should check for both possibilities.
 323 .TP
 324 .B EAGAIN
 325 (Internet domain datagram sockets)
 326 The socket referred to by
 327 .I sockfd
 328 had not previously been bound to an address and,
 329 upon attempting to bind it to an ephemeral port,
 330 it was determined that all port numbers in the ephemeral port range
 331 are currently in use.
 332 See the discussion of
 333 .I /proc/sys/net/ipv4/ip_local_port_range
 334 in
 335 .BR ip (7).
 336 .TP
 337 .B EBADF
 338 An invalid descriptor was specified.
 339 .TP
 340 .B ECONNRESET
 341 Connection reset by peer.
 342 .TP
 343 .B EDESTADDRREQ
 344 The socket is not connection-mode, and no peer address is set.
 345 .TP
 346 .B EFAULT
 347 An invalid user space address was specified for an argument.
 348 .TP
 349 .B EINTR
 350 A signal occurred before any data was transmitted; see
 351 .BR signal (7).
 352 .TP
 353 .B EINVAL
 354 Invalid argument passed.
 355 .TP
 356 .B EISCONN
 357 The connection-mode socket was connected already but a
 358 recipient was specified.
 359 (Now either this error is returned, or the recipient specification
 360 is ignored.)
 361 .TP
 362 .B EMSGSIZE
 363 The socket type
 364 .\" (e.g., SOCK_DGRAM )
 365 requires that message be sent atomically, and the size
 366 of the message to be sent made this impossible.
 367 .TP
 368 .B ENOBUFS
 369 The output queue for a network interface was full.
 370 This generally indicates that the interface has stopped sending,
 371 but may be caused by transient congestion.
 372 (Normally, this does not occur in Linux.
 373 Packets are just silently dropped
 374 when a device queue overflows.)
 375 .TP
 376 .B ENOMEM
 377 No memory available.
 378 .TP
 379 .B ENOTCONN
 380 The socket is not connected, and no target has been given.
 381 .TP
 382 .B ENOTSOCK
 383 The argument
 384 .I sockfd
 385 is not a socket.
 386 .TP
 387 .B EOPNOTSUPP
 388 Some bit in the
 389 .I flags
 390 argument is inappropriate for the socket type.
 391 .TP
 392 .B EPIPE
 393 The local end has been shut down on a connection oriented socket.
 394 In this case, the process
 395 will also receive a
 396 .B SIGPIPE
 397 unless
 398 .B MSG_NOSIGNAL
 399 is set.
 400 .SH CONFORMING TO
 401 4.4BSD, SVr4, POSIX.1-2001.
 402 These function calls appeared in 4.2BSD.
 403 .LP
 404 POSIX.1-2001 describes only the
 405 .B MSG_OOB
 406 and
 407 .B MSG_EOR
 408 flags.
 409 POSIX.1-2008 adds a specification of
 410 .BR MSG_NOSIGNAL .
 411 The
 412 .B MSG_CONFIRM
 413 flag is a Linux extension.
 414 .SH NOTES
 415 According to POSIX.1-2001, the
 416 .I msg_controllen
 417 field of the
 418 .I msghdr
 419 structure should be typed as
 420 .IR socklen_t ,
 421 but glibc currently types it as
 422 .IR size_t .
 423 .\" glibc bug raised 12 Mar 2006
 424 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 425 .\" The problem is an underlying kernel issue: the size of the
 426 .\" __kernel_size_t type used to type this field varies
 427 .\" across architectures, but socklen_t is always 32 bits.
 428
 429 See
 430 .BR sendmmsg (2)
 431 for information about a Linux-specific system call
 432 that can be used to transmit multiple datagrams in a single call.
 433 .SH BUGS
 434 Linux may return
 435 .B EPIPE
 436 instead of
 437 .BR ENOTCONN .
 438 .SH EXAMPLE
 439 An example of the use of
 440 .BR sendto ()
 441 is shown in
 442 .BR getaddrinfo (3).
 443 .SH SEE ALSO
 444 .BR fcntl (2),
 445 .BR getsockopt (2),
 446 .BR recv (2),
 447 .BR select (2),
 448 .BR sendfile (2),
 449 .BR sendmmsg (2),
 450 .BR shutdown (2),
 451 .BR socket (2),
 452 .BR write (2),
 453 .BR cmsg (3),
 454 .BR ip (7),
 455 .BR socket (7),
 456 .BR tcp (7),
 457 .BR udp (7)
 458 .SH COLOPHON
 459 This page is part of release 3.79 of the Linux
 460 .I man-pages
 461 project.
 462 A description of the project,
 463 information about reporting bugs,
 464 and the latest version of this page,
 465 can be found at
 466 \%http://www.kernel.org/doc/man\-pages/.