bsd/man/man2/send.2

   1 .\"     $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej 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. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)send.2      8.2 (Berkeley) 2/21/94
  35 .\"
  36 .Dd February 21, 1994
  37 .Dt SEND 2
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm send ,
  41 .Nm sendmsg ,
  42 .Nm sendto
  43 .Nd send a message from a socket
  44 .Sh SYNOPSIS
  45 .Fd #include <sys/socket.h>
  46 .Ft ssize_t
  47 .Fo send
  48 .Fa "int socket"
  49 .Fa "const void *buffer"
  50 .Fa "size_t length"
  51 .Fa "int flags"
  52 .Fc
  53 .Ft ssize_t
  54 .Fo sendmsg
  55 .Fa "int socket"
  56 .Fa "const struct msghdr *message"
  57 .Fa "int flags"
  58 .Fc
  59 .Ft ssize_t
  60 .Fo sendto
  61 .Fa "int socket"
  62 .Fa "const void *buffer"
  63 .Fa "size_t length"
  64 .Fa "int flags"
  65 .Fa "const struct sockaddr *dest_addr"
  66 .Fa "socklen_t dest_len"
  67 .Fc
  68 .Sh DESCRIPTION
  69 .Fn send ,
  70 .Fn sendto ,
  71 and
  72 .Fn sendmsg
  73 are used to transmit a message to another socket.
  74 .Fn send
  75 may be used only when the socket is in a
  76 .Em connected
  77 state, while
  78 .Fn sendto
  79 and
  80 .Fn sendmsg
  81 may be used at any time.
  82 .Pp
  83 The address of the target is given by
  84 .Fa dest_addr
  85 with
  86 .Fa dest_len
  87 specifying its size.
  88 The length of the message is given by
  89 .Fa length .
  90 If the message is too long to pass atomically through the
  91 underlying protocol, the error
  92 .Er EMSGSIZE
  93 is returned, and
  94 the message is not transmitted.
  95 .Pp
  96 No indication of failure to deliver is implicit in a
  97 .Fn send .
  98 Locally detected errors are indicated by a return value of -1.
  99 .Pp
 100 If no messages space is available at the socket to hold
 101 the message to be transmitted, then
 102 .Fn send
 103 normally blocks, unless the socket has been placed in
 104 non-blocking I/O mode.
 105 The
 106 .Xr select 2
 107 call may be used to determine when it is possible to
 108 send more data.
 109 .Pp
 110 The
 111 .Fa flags
 112 parameter may include one or more of the following:
 113 .Bd -literal
 114 #define MSG_OOB        0x1  /* process out-of-band data */
 115 #define MSG_DONTROUTE  0x4  /* bypass routing, use direct interface */
 116 .Ed
 117 .Pp
 118 The flag
 119 .Dv MSG_OOB
 120 is used to send
 121 .Dq out-of-band
 122 data on sockets that support this notion (e.g.
 123 .Dv SOCK_STREAM ) ;
 124 the underlying protocol must also support
 125 .Dq out-of-band
 126 data.
 127 .Dv MSG_DONTROUTE
 128 is usually used only by diagnostic or routing programs.
 129 .Pp
 130 The
 131 .Fn sendmsg
 132 system call uses a
 133 .Fa msghdr
 134 structure to minimize the number of directly supplied arguments.
 135 The
 136 .Fa msg_iov
 137 and
 138 .Fa msg_iovlen
 139 fields of message specify zero or more buffers
 140 containing the data to be sent.
 141 .Fa msg_iov
 142 points to an array of iovec structures;
 143 .Fa msg_iovlen
 144 shall be set to the dimension of this array.
 145 In each iovec structure, the
 146 .Fa iov_base
 147 field specifies a storage area and
 148 the
 149 .Fa iov_len
 150 field gives its size in bytes. Some of these sizes can be zero.
 151 The data from each storage area indicated by
 152 .Fa msg_iov
 153 is sent in turn.
 154 See
 155 .Xr recv 2
 156 for a complete description of the
 157 .Fa msghdr
 158 structure.
 159 .Sh RETURN VALUES
 160 Upon successful completion,
 161 the number of bytes which were sent is returned.
 162 Otherwise, -1 is returned and the global variable
 163 .Va errno
 164 is set to indicate the error.
 165 .Sh ERRORS
 166 The
 167 .Fn send ,
 168 .Fn sendmsg ,
 169 and
 170 .Fn sendto
 171 system calls will fail if:
 172 .Bl -tag -width Er
 173 .\" ===========
 174 .It Bq Er EACCES
 175 The SO_BROADCAST option is not set on the socket
 176 and a broadcast address is given as the destination.
 177 .\" ===========
 178 .It Bq Er EAGAIN
 179 The socket is marked non-blocking
 180 and the requested operation would block.
 181 .\" ===========
 182 .It Bq Er EBADF
 183 An invalid descriptor is specified.
 184 .\" ===========
 185 .It Bq Er ECONNRESET
 186 A connection is forcibly closed by a peer.
 187 .\" ===========
 188 .It Bq Er EFAULT
 189 An invalid user space address is specified for a parameter.
 190 .\" ===========
 191 .It Bq Er EHOSTUNREACH
 192 The destination address specifies an unreachable host.
 193 .\" ===========
 194 .It Bq Er EINTR
 195 A signal interrupts the system call
 196 before any data is transmitted.
 197 .\" ===========
 198 .It Bq Er EMSGSIZE
 199 The socket requires that message be sent atomically,
 200 and the size of the message to be sent makes this impossible.
 201 .Dv IOV_MAX .
 202 .\" ===========
 203 .It Bq Er ENETDOWN
 204 The local network interface used to reach the destination is down.
 205 .\" ===========
 206 .It Bq Er ENETUNREACH
 207 No route to the network is present.
 208 .\" ===========
 209 .It Bq Er ENOBUFS
 210 The system is unable to allocate an internal buffer.
 211 The operation may succeed when buffers become available.
 212 .\" ===========
 213 .It Bq Er ENOBUFS
 214 The output queue for a network interface is full.
 215 This generally indicates that the interface has stopped sending,
 216 but may be caused by transient congestion.
 217 .\" ===========
 218 .It Bq Er ENOTSOCK
 219 The argument
 220 .Fa socket
 221 is not a socket.
 222 .\" ===========
 223 .It Bq Er EOPNOTSUPP
 224 .Fa socket
 225 does not support (some of) the option(s) specified in
 226 .Fa flags .
 227 .\" ===========
 228 .It Bq Er EPIPE
 229 The socket is shut down for writing
 230 or the socket is connection-mode and is no longer connected.
 231 In the latter case, and if the socket is of type SOCK_STREAM,
 232 the SIGPIPE signal is generated to the calling thread.
 233 .El
 234 .Pp
 235 The
 236 .Fn sendmsg
 237 and
 238 .Fn sendto
 239 system calls will fail if:
 240 .Bl -tag -width Er
 241 .\" ===========
 242 .It Bq Er EAFNOSUPPORT
 243 Addresses in the specified address family cannot be used
 244 with this socket.
 245 .\" ===========
 246 .It Bq Er EDESTADDRREQ
 247 The socket is not connection-mode and does not have its peer address set,
 248 and no destination address is specified.
 249 .\" ===========
 250 .It Bq Er EISCONN
 251 A destination address was specified and the socket is already connected.
 252 .\" ===========
 253 .It Bq Er ENOENT
 254 A component of the pathname does not name an existing file
 255 or the path name is an empty string.
 256 .\" ===========
 257 .It Bq Er ENOMEM
 258 Insufficient memory is available to fulfill the request.
 259 .\" ===========
 260 .It Bq Er ENOTCONN
 261 The socket is connection-mode, but is not connected.
 262 .\" ===========
 263 .It Bq Er ENOTDIR
 264 A component of the path prefix of the pathname in the socket address
 265 is not a directory.
 266 .El
 267 .Pp
 268 The
 269 .Fn send
 270 system call will fail if:
 271 .Bl -tag -width Er
 272 .\" ===========
 273 .It Bq Er EDESTADDRREQ
 274 The socket is not connection-mode and no peer address is set.
 275 .\" ===========
 276 .It Bq Er ENOTCONN
 277 The socket is not connected or otherwise has not had the peer pre-specified.
 278 .El
 279 .Pp
 280 The
 281 .Fn sendmsg
 282 system call will fail if:
 283 .Bl -tag -width Er
 284 .\" ===========
 285 .It Bq Er EINVAL
 286 The sum of the iov_len values overflows an ssize_t.
 287 .\" ===========
 288 .It Bq Er EMSGSIZE
 289 The socket requires that message be sent atomically,
 290 and the size of the message to be sent makes this impossible,
 291 or the msg_iovlen member of the msghdr structure pointed to by message
 292 is less than or equal to 0 or is greater than
 293 .Dv IOV_MAX .
 294 .El
 295 .Sh LEGACY SYNOPSIS
 296 .Fd #include <sys/types.h>
 297 .Fd #include <sys/socket.h>
 298 .Pp
 299 The include file
 300 .In sys/types.h is necessary.
 301 .Sh SEE ALSO
 302 .Xr fcntl 2 ,
 303 .Xr getsockopt 2 ,
 304 .Xr recv 2 ,
 305 .Xr select 2 ,
 306 .Xr socket 2 ,
 307 .Xr write 2 ,
 308 .Xr compat 5
 309 .Sh HISTORY
 310 The
 311 .Fn send
 312 function call appeared in
 313 .Bx 4.2 .