lib/libc/sys/send.2

   1 .\"     $NetBSD: send.2,v 1.27 2008/05/09 15:52:50 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)send.2      8.2 (Berkeley) 2/21/94
  31 .\"
  32 .Dd May 9, 2008
  33 .Dt SEND 2
  34 .Os
  35 .Sh NAME
  36 .Nm send ,
  37 .Nm sendto ,
  38 .Nm sendmsg
  39 .Nd send a message from a socket
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/socket.h
  44 .Ft ssize_t
  45 .Fn send "int s" "const void *msg" "size_t len" "int flags"
  46 .Ft ssize_t
  47 .Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
  48 .Ft ssize_t
  49 .Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
  50 .Sh DESCRIPTION
  51 .Fn send ,
  52 .Fn sendto ,
  53 and
  54 .Fn sendmsg
  55 are used to transmit a message to another socket.
  56 .Fn send
  57 may be used only when the socket is in a
  58 .Em connected
  59 state, while
  60 .Fn sendto
  61 and
  62 .Fn sendmsg
  63 may be used at any time.
  64 .Pp
  65 The address of the target is given by
  66 .Fa to
  67 with
  68 .Fa tolen
  69 specifying its size.
  70 The length of the message is given by
  71 .Fa len .
  72 If the message is too long to pass atomically through the
  73 underlying protocol, the error
  74 .Er EMSGSIZE
  75 is returned, and
  76 the message is not transmitted.
  77 .Pp
  78 No indication of failure to deliver is implicit in a
  79 .Fn send .
  80 Locally detected errors are indicated by a return value of \-1.
  81 .Pp
  82 If no messages space is available at the socket to hold
  83 the message to be transmitted, then
  84 .Fn send
  85 normally blocks, unless the socket has been placed in
  86 non-blocking I/O mode.
  87 The
  88 .Xr select 2
  89 or
  90 .Xr poll 2
  91 call may be used to determine when it is possible to
  92 send more data.
  93 .Pp
  94 The
  95 .Fa flags
  96 parameter may include one or more of the following:
  97 .Bd -literal
  98 #define MSG_OOB         0x0001 /* process out-of-band data */
  99 #define MSG_PEEK        0x0002 /* peek at incoming message */
 100 #define MSG_DONTROUTE   0x0004 /* bypass routing, use direct interface */
 101 #define MSG_EOR         0x0008 /* data completes record */
 102 #define MSG_NOSIGNAL    0x0400 /* do not generate SIGPIPE on EOF */
 103 .Ed
 104 .Pp
 105 The flag
 106 .Dv MSG_OOB
 107 is used to send
 108 .Dq out-of-band
 109 data on sockets that support this notion (e.g.
 110 .Dv SOCK_STREAM ) ;
 111 the underlying protocol must also support
 112 .Dq out-of-band
 113 data.
 114 .Dv MSG_EOR
 115 is used to indicate a record mark for protocols which support the
 116 concept.
 117 .\" .Dv MSG_EOF
 118 .\" requests that the sender side of a socket be shut down, and that an
 119 .\" appropriate indication be sent at the end of the specified data;
 120 .\" this flag is only implemented for
 121 .\" .Dv SOCK_STREAM
 122 .\" sockets in the
 123 .\" .Dv PF_INET
 124 .\" protocol family, and is used to implement Transaction
 125 .\" .Tn TCP
 126 .\" (see
 127 .\" .Xr ttcp 4 ) .
 128 .Dv MSG_DONTROUTE
 129 is usually used only by diagnostic or routing programs.
 130 .Pp
 131 See
 132 .Xr recv 2
 133 for a description of the
 134 .Fa msghdr
 135 structure.
 136 .Dv MSG_NOSIGNAL
 137 is used to prevent
 138 .Dv SIGPIPE
 139 generation when writing a socket that
 140 may be closed.
 141 .Sh RETURN VALUES
 142 The call returns the number of characters sent, or \-1
 143 if an error occurred.
 144 .Sh ERRORS
 145 .Fn send ,
 146 .Fn sendto ,
 147 and
 148 .Fn sendmsg
 149 fail if:
 150 .Bl -tag -width Er
 151 .It Bq Er EBADF
 152 An invalid descriptor was specified.
 153 .It Bq Er ENOTSOCK
 154 The argument
 155 .Fa s
 156 is not a socket.
 157 .It Bq Er EFAULT
 158 An invalid user space address was specified for a parameter.
 159 .It Bq Er EMSGSIZE
 160 The socket requires that message be sent atomically,
 161 and the size of the message to be sent made this impossible.
 162 .It Bq Er EPIPE
 163 In a connected socket the connection has been broken.
 164 .It Bq Er EDSTADDRREQ
 165 In a non-connected socket a destination address has not been specified.
 166 .It Bq Er EAGAIN|EWOULDBLOCK
 167 The socket is marked non-blocking and the requested operation
 168 would block.
 169 .It Bq Er ENOBUFS
 170 The system was unable to allocate an internal buffer.
 171 The operation may succeed when buffers become available.
 172 .It Bq Er ENOBUFS
 173 The output queue for a network interface was full.
 174 This generally indicates that the interface has stopped sending,
 175 but may be caused by transient congestion.
 176 .It Bq Er EACCES
 177 The SO_BROADCAST option is not set on the socket, and a broadcast address
 178 was given as the destination.
 179 .It Bq Er EHOSTUNREACH
 180 The destination for the message is unreachable.
 181 .It Bq Er EHOSTDOWN
 182 The destination is a host on the local subnet and does not respond to
 183 .Xr arp 4 .
 184 .It Bq Er EINVAL
 185 The total length of the I/O is more than can be expressed by the ssize_t
 186 return value.
 187 .It Bq Er EAFNOSUPPORT
 188 Addresses in the specified address family cannot be used with this socket.
 189 .El
 190 .Pp
 191 .Fn sendto
 192 will also fail if:
 193 .Bl -tag -width Er
 194 .It Bq Er EISCONN
 195 A destination address was specified and the socket is already connected.
 196 .El
 197 .Pp
 198 .Fn sendmsg
 199 will also fail if:
 200 .Bl -tag -width Er
 201 .It Bq Er EMSGSIZE
 202 The
 203 .Fa msg_iovlen
 204 member of the
 205 .Fa msg
 206 structure is less than or equal to 0
 207 or is greater than
 208 .Dv {IOV_MAX} .
 209 .El
 210 .Sh SEE ALSO
 211 .Xr fcntl 2 ,
 212 .Xr getsockopt 2 ,
 213 .Xr recv 2 ,
 214 .Xr select 2 ,
 215 .Xr socket 2 ,
 216 .Xr write 2
 217 .Sh HISTORY
 218 The
 219 .Fn send
 220 function call appeared in
 221 .Bx 4.2 .