man2/send.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  33 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
  34 .\" Modified Oct 1998 by Andi Kleen
  35 .\" Modified Oct 2003 by aeb
  36 .\" Modified 2004-07-01 by mtk
  37 .\"
  38 .TH SEND 2 2004-07-01 "Linux" "Linux Programmer's Manual"
  39 .SH NAME
  40 send, sendto, sendmsg \- send a message on a socket
  41 .SH SYNOPSIS
  42 .nf
  43 .B #include <sys/types.h>
  44 .B #include <sys/socket.h>
  45 .sp
  46 .BI "ssize_t send(int " s ", const void *" buf ", size_t " len \
  47 ", int " flags );
  48
  49 .BI "ssize_t sendto(int " s ", const void *" buf ", size_t " len \
  50 ", int " flags ,
  51 .BI "               const struct sockaddr *" to ", socklen_t " tolen );
  52
  53 .BI "ssize_t sendmsg(int " s ", const struct msghdr *" msg \
  54 ", int " flags );
  55 .fi
  56 .SH DESCRIPTION
  57 The system calls
  58 .BR send (),
  59 .BR sendto (),
  60 and
  61 .BR sendmsg ()
  62 are used to transmit a message to another socket.
  63 .PP
  64 The
  65 .BR send ()
  66 call may be used only when the socket is in a
  67 .I connected
  68 state (so that the intended recipient is known).
  69 The only difference between
  70 .BR send ()
  71 and
  72 .BR write (2)
  73 is the presence of
  74 .IR flags .
  75 With zero
  76 .I flags
  77 argument,
  78 .BR send ()
  79 is equivalent to
  80 .BR write (2).
  81 Also,
  82 .RI send( s , buf , len , flags )
  83 is equivalent to
  84 .RI sendto( s , buf , len , flags ,NULL,0).
  85 .PP
  86 The argument
  87 .I s
  88 is the file descriptor of the sending socket.
  89 .PP
  90 If
  91 .BR sendto ()
  92 is used on a connection-mode
  93 .RB ( SOCK_STREAM ,
  94 .BR SOCK_SEQPACKET )
  95 socket, the arguments
  96 .I to
  97 and
  98 .I tolen
  99 are ignored (and the error
 100 .B EISCONN
 101 may be returned when they are
 102 not NULL and 0), and the error
 103 .B ENOTCONN
 104 is returned when the socket was not actually connected.
 105 Otherwise, the address of the target is given by
 106 .I to
 107 with
 108 .I tolen
 109 specifying its size.
 110 For
 111 .BR sendmsg (),
 112 the address of the target is given by
 113 .IR msg.msg_name ,
 114 with
 115 .I msg.msg_namelen
 116 specifying its size.
 117 .PP
 118 For
 119 .BR send ()
 120 and
 121 .BR sendto (),
 122 the message is found in
 123 .I buf
 124 and has length
 125 .IR len .
 126 For
 127 .BR sendmsg (),
 128 the message is pointed to by the elements of the array
 129 .IR msg.msg_iov .
 130 The
 131 .BR sendmsg ()
 132 call also allows sending ancillary data (also known as control information).
 133 .PP
 134 If the message is too long to pass atomically through the
 135 underlying protocol, the error
 136 .B EMSGSIZE
 137 is returned, and the message is not transmitted.
 138 .PP
 139 No indication of failure to deliver is implicit in a
 140 .BR send ().
 141 Locally detected errors are indicated by a return value of \-1.
 142 .PP
 143 When the message does not fit into the send buffer of the socket,
 144 .BR send ()
 145 normally blocks, unless the socket has been placed in non-blocking I/O
 146 mode.
 147 In non-blocking mode it would return
 148 .B EAGAIN
 149 in this case.
 150 The
 151 .BR select (2)
 152 call may be used to determine when it is possible to send more data.
 153 .PP
 154 The
 155 .I flags
 156 argument is the bitwise OR
 157 of zero or more of the following flags.
 158 .\" FIXME ? document MSG_PROXY (which went away in 2.3.15)
 159 .TP
 160 .BR MSG_CONFIRM " (Linux 2.3+ only)"
 161 Tell the link layer that forward progress happened: you got a successful
 162 reply from the other side.
 163 If the link layer doesn't get this
 164 it will regularly reprobe the neighbor (e.g., via a unicast ARP).
 165 Only valid on
 166 .B SOCK_DGRAM
 167 and
 168 .B SOCK_RAW
 169 sockets and currently only implemented for IPv4 and IPv6.
 170 See
 171 .BR arp (7)
 172 for details.
 173 .TP
 174 .B MSG_DONTROUTE
 175 Don't use a gateway to send out the packet, only send to hosts on
 176 directly connected networks.
 177 This is usually used only
 178 by diagnostic or routing programs.
 179 This is only defined for protocol
 180 families that route; packet sockets don't.
 181 .TP
 182 .B MSG_DONTWAIT
 183 Enables non-blocking operation; if the operation would block,
 184 .B EAGAIN
 185 is returned (this can also be enabled using the
 186 .B O_NONBLOCK
 187 with the
 188 .B F_SETFL
 189 .BR fcntl (2)).
 190 .TP
 191 .B MSG_EOR
 192 Terminates a record (when this notion is supported, as for sockets of type
 193 .BR SOCK_SEQPACKET ).
 194 .TP
 195 .BR MSG_MORE " (Since Linux 2.4.4)"
 196 The caller has more data to send.
 197 This flag is used with TCP sockets to obtain the same effect
 198 as the
 199 .B TCP_CORK
 200 socket option (see
 201 .BR tcp (7)),
 202 with the difference that this flag can be set on a per-call basis.
 203
 204 Since Linux 2.6, this flag is also supported for UDP sockets, and informs
 205 the kernel to package all of the data sent in calls with this flag set
 206 into a single datagram which is only transmitted when a call is performed
 207 that does not specify this flag.
 208 (See also the
 209 .B UDP_CORK
 210 socket option described in
 211 .BR udp (7).)
 212 .TP
 213 .B MSG_NOSIGNAL
 214 Requests not to send
 215 .B SIGPIPE
 216 on errors on stream oriented sockets when the other end breaks the
 217 connection.
 218 The
 219 .B EPIPE
 220 error is still returned.
 221 .TP
 222 .B MSG_OOB
 223 Sends
 224 .I out-of-band
 225 data on sockets that support this notion (e.g., of type
 226 .BR SOCK_STREAM );
 227 the underlying protocol must also support
 228 .I out-of-band
 229 data.
 230 .PP
 231 The definition of the
 232 .I msghdr
 233 structure follows.
 234 See
 235 .BR recv (2)
 236 and below for an exact description of its fields.
 237 .in +4n
 238 .nf
 239
 240 struct msghdr {
 241     void         *msg_name;       /* optional address */
 242     socklen_t     msg_namelen;    /* size of address */
 243     struct iovec *msg_iov;        /* scatter/gather array */
 244     size_t        msg_iovlen;     /* # elements in msg_iov */
 245     void         *msg_control;    /* ancillary data, see below */
 246     socklen_t     msg_controllen; /* ancillary data buffer len */
 247     int           msg_flags;      /* flags on received message */
 248 };
 249 .fi
 250 .in
 251 .PP
 252 You may send control information using the
 253 .I msg_control
 254 and
 255 .I msg_controllen
 256 members.
 257 The maximum control buffer length the kernel can process is limited
 258 per socket by the
 259 .I net.core.optmem_max
 260 sysctl; see
 261 .BR socket (7).
 262 .\" Still to be documented:
 263 .\"  Send file descriptors and user credentials using the
 264 .\"  msg_control* fields.
 265 .\"  The flags returned in msg_flags.
 266 .SH "RETURN VALUE"
 267 On success, these calls return the number of characters sent.
 268 On error, \-1 is returned, and
 269 .I errno
 270 is set appropriately.
 271 .SH ERRORS
 272 These are some standard errors generated by the socket layer.
 273 Additional errors
 274 may be generated and returned from the underlying protocol modules;
 275 see their respective manual pages.
 276 .TP
 277 .B EACCES
 278 (For Unix domain sockets, which are identified by pathname)
 279 Write permission is denied on the destination socket file,
 280 or search permission is denied for one of the directories
 281 the path prefix.
 282 (See
 283 .BR path_resolution (7).)
 284 .TP
 285 .BR EAGAIN " or " EWOULDBLOCK
 286 The socket is marked non-blocking and the requested operation
 287 would block.
 288 .TP
 289 .B EBADF
 290 An invalid descriptor was specified.
 291 .TP
 292 .B ECONNRESET
 293 Connection reset by peer.
 294 .TP
 295 .B EDESTADDRREQ
 296 The socket is not connection-mode, and no peer address is set.
 297 .TP
 298 .B EFAULT
 299 An invalid user space address was specified for an argument.
 300 .TP
 301 .B EINTR
 302 A signal occurred before any data was transmitted; see
 303 .BR signal (7).
 304 .TP
 305 .B EINVAL
 306 Invalid argument passed.
 307 .TP
 308 .B EISCONN
 309 The connection-mode socket was connected already but a
 310 recipient was specified.
 311 (Now either this error is returned, or the recipient specification
 312 is ignored.)
 313 .TP
 314 .B EMSGSIZE
 315 The socket type
 316 .\" (e.g., SOCK_DGRAM )
 317 requires that message be sent atomically, and the size
 318 of the message to be sent made this impossible.
 319 .TP
 320 .B ENOBUFS
 321 The output queue for a network interface was full.
 322 This generally indicates that the interface has stopped sending,
 323 but may be caused by transient congestion.
 324 (Normally, this does not occur in Linux.
 325 Packets are just silently dropped
 326 when a device queue overflows.)
 327 .TP
 328 .B ENOMEM
 329 No memory available.
 330 .TP
 331 .B ENOTCONN
 332 The socket is not connected, and no target has been given.
 333 .TP
 334 .B ENOTSOCK
 335 The argument
 336 .I s
 337 is not a socket.
 338 .TP
 339 .B EOPNOTSUPP
 340 Some bit in the
 341 .I flags
 342 argument is inappropriate for the socket type.
 343 .TP
 344 .B EPIPE
 345 The local end has been shut down on a connection oriented socket.
 346 In this case the process
 347 will also receive a
 348 .B SIGPIPE
 349 unless
 350 .B MSG_NOSIGNAL
 351 is set.
 352 .SH "CONFORMING TO"
 353 4.4BSD, SVr4, POSIX.1-2001.
 354 These function calls appeared in 4.2BSD.
 355 .LP
 356 POSIX.1-2001 only describes the
 357 .B MSG_OOB
 358 and
 359 .B MSG_EOR
 360 flags.
 361 The
 362 .B MSG_CONFIRM
 363 flag is a Linux extension.
 364 .SH NOTES
 365 The prototypes given above follow the Single Unix Specification,
 366 as glibc2 also does; the
 367 .I flags
 368 argument was \fIint\fP in 4.x BSD, but \fIunsigned int\fP in libc4 and libc5;
 369 the
 370 .I len
 371 argument was \fIint\fP in 4.x BSD and libc4, but \fIsize_t\fP in libc5;
 372 the
 373 .I tolen
 374 argument was \fIint\fP in 4.x BSD and libc4 and libc5.
 375 See also
 376 .BR accept (2).
 377
 378 According to POSIX.1-2001, the
 379 .I msg_controllen
 380 field of the
 381 .I msghdr
 382 structure should be typed as
 383 .IR socklen_t ,
 384 but glibc currently (2.4) types it as
 385 .IR size_t .
 386 .\" glibc bug raised 12 Mar 2006
 387 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 388 .\" The problem is an underlying kernel issue: the size of the
 389 .\" __kernel_size_t type used to type this field varies
 390 .\" across architectures, but socklen_t is always 32 bits.
 391 .SH BUGS
 392 Linux may return
 393 .B EPIPE
 394 instead of
 395 .BR ENOTCONN .
 396 .SH EXAMPLE
 397 An example of the use of
 398 .BR sendto ()
 399 is shown in
 400 .BR getaddrinfo (3).
 401 .SH "SEE ALSO"
 402 .BR fcntl (2),
 403 .BR getsockopt (2),
 404 .BR recv (2),
 405 .BR select (2),
 406 .BR sendfile (2),
 407 .BR shutdown (2),
 408 .BR socket (2),
 409 .BR write (2),
 410 .BR cmsg (3),
 411 .BR ip (7),
 412 .BR socket (7),
 413 .BR tcp (7),
 414 .BR udp (7)