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 2013-12-12 "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 .PP
 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 .PP
 240 The definition of the
 241 .I msghdr
 242 structure follows.
 243 See
 244 .BR recv (2)
 245 and below for an exact description of its fields.
 246 .in +4n
 247 .nf
 248
 249 struct msghdr {
 250     void         *msg_name;       /* optional address */
 251     socklen_t     msg_namelen;    /* size of address */
 252     struct iovec *msg_iov;        /* scatter/gather array */
 253     size_t        msg_iovlen;     /* # elements in msg_iov */
 254     void         *msg_control;    /* ancillary data, see below */
 255     size_t        msg_controllen; /* ancillary data buffer len */
 256     int           msg_flags;      /* flags on received message */
 257 };
 258 .fi
 259 .in
 260 .PP
 261 You may send control information using the
 262 .I msg_control
 263 and
 264 .I msg_controllen
 265 members.
 266 The maximum control buffer length the kernel can process is limited
 267 per socket by the value in
 268 .IR /proc/sys/net/core/optmem_max ;
 269 see
 270 .BR socket (7).
 271 .\" Still to be documented:
 272 .\"  Send file descriptors and user credentials using the
 273 .\"  msg_control* fields.
 274 .\"  The flags returned in msg_flags.
 275 .SH RETURN VALUE
 276 On success, these calls return the number of bytes sent.
 277 On error, \-1 is returned, and
 278 .I errno
 279 is set appropriately.
 280 .SH ERRORS
 281 These are some standard errors generated by the socket layer.
 282 Additional errors
 283 may be generated and returned from the underlying protocol modules;
 284 see their respective manual pages.
 285 .TP
 286 .B EACCES
 287 (For UNIX domain sockets, which are identified by pathname)
 288 Write permission is denied on the destination socket file,
 289 or search permission is denied for one of the directories
 290 the path prefix.
 291 (See
 292 .BR path_resolution (7).)
 293 .sp
 294 (For UDP sockets) An attempt was made to send to a
 295 network/broadcast address as though it was a unicast address.
 296 .TP
 297 .BR EAGAIN " or " EWOULDBLOCK
 298 .\" Actually EAGAIN on Linux
 299 The socket is marked nonblocking and the requested operation
 300 would block.
 301 POSIX.1-2001 allows either error to be returned for this case,
 302 and does not require these constants to have the same value,
 303 so a portable application should check for both possibilities.
 304 .TP
 305 .B EBADF
 306 An invalid descriptor was specified.
 307 .TP
 308 .B ECONNRESET
 309 Connection reset by peer.
 310 .TP
 311 .B EDESTADDRREQ
 312 The socket is not connection-mode, and no peer address is set.
 313 .TP
 314 .B EFAULT
 315 An invalid user space address was specified for an argument.
 316 .TP
 317 .B EINTR
 318 A signal occurred before any data was transmitted; see
 319 .BR signal (7).
 320 .TP
 321 .B EINVAL
 322 Invalid argument passed.
 323 .TP
 324 .B EISCONN
 325 The connection-mode socket was connected already but a
 326 recipient was specified.
 327 (Now either this error is returned, or the recipient specification
 328 is ignored.)
 329 .TP
 330 .B EMSGSIZE
 331 The socket type
 332 .\" (e.g., SOCK_DGRAM )
 333 requires that message be sent atomically, and the size
 334 of the message to be sent made this impossible.
 335 .TP
 336 .B ENOBUFS
 337 The output queue for a network interface was full.
 338 This generally indicates that the interface has stopped sending,
 339 but may be caused by transient congestion.
 340 (Normally, this does not occur in Linux.
 341 Packets are just silently dropped
 342 when a device queue overflows.)
 343 .TP
 344 .B ENOMEM
 345 No memory available.
 346 .TP
 347 .B ENOTCONN
 348 The socket is not connected, and no target has been given.
 349 .TP
 350 .B ENOTSOCK
 351 The argument
 352 .I sockfd
 353 is not a socket.
 354 .TP
 355 .B EOPNOTSUPP
 356 Some bit in the
 357 .I flags
 358 argument is inappropriate for the socket type.
 359 .TP
 360 .B EPIPE
 361 The local end has been shut down on a connection oriented socket.
 362 In this case, the process
 363 will also receive a
 364 .B SIGPIPE
 365 unless
 366 .B MSG_NOSIGNAL
 367 is set.
 368 .SH CONFORMING TO
 369 4.4BSD, SVr4, POSIX.1-2001.
 370 These function calls appeared in 4.2BSD.
 371 .LP
 372 POSIX.1-2001 describes only the
 373 .B MSG_OOB
 374 and
 375 .B MSG_EOR
 376 flags.
 377 POSIX.1-2008 adds a specification of
 378 .BR MSG_NOSIGNAL .
 379 The
 380 .B MSG_CONFIRM
 381 flag is a Linux extension.
 382 .SH NOTES
 383 The prototypes given above follow the Single UNIX Specification,
 384 as glibc2 also does; the
 385 .I flags
 386 argument was \fIint\fP in 4.x BSD, but \fIunsigned int\fP in libc4 and libc5;
 387 the
 388 .I len
 389 argument was \fIint\fP in 4.x BSD and libc4, but \fIsize_t\fP in libc5;
 390 the
 391 .I addrlen
 392 argument was \fIint\fP in 4.x BSD and libc4 and libc5.
 393 See also
 394 .BR accept (2).
 395
 396 According to POSIX.1-2001, the
 397 .I msg_controllen
 398 field of the
 399 .I msghdr
 400 structure should be typed as
 401 .IR socklen_t ,
 402 but glibc currently types it as
 403 .IR size_t .
 404 .\" glibc bug raised 12 Mar 2006
 405 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 406 .\" The problem is an underlying kernel issue: the size of the
 407 .\" __kernel_size_t type used to type this field varies
 408 .\" across architectures, but socklen_t is always 32 bits.
 409
 410 See
 411 .BR sendmmsg (2)
 412 for information about a Linux-specific system call
 413 that can be used to transmit multiple datagrams in a single call.
 414 .SH BUGS
 415 Linux may return
 416 .B EPIPE
 417 instead of
 418 .BR ENOTCONN .
 419 .SH EXAMPLE
 420 An example of the use of
 421 .BR sendto ()
 422 is shown in
 423 .BR getaddrinfo (3).
 424 .SH SEE ALSO
 425 .BR fcntl (2),
 426 .BR getsockopt (2),
 427 .BR recv (2),
 428 .BR select (2),
 429 .BR sendfile (2),
 430 .BR sendmmsg (2),
 431 .BR shutdown (2),
 432 .BR socket (2),
 433 .BR write (2),
 434 .BR cmsg (3),
 435 .BR ip (7),
 436 .BR socket (7),
 437 .BR tcp (7),
 438 .BR udp (7)
 439 .SH COLOPHON
 440 This page is part of release 3.64 of the Linux
 441 .I man-pages
 442 project.
 443 A description of the project,
 444 and information about reporting bugs,
 445 can be found at
 446 \%http://www.kernel.org/doc/man\-pages/.