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 *buffer"
  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 See
 131 .Xr recv 2
 132 for a description of the
 133 .Fa msghdr
 134 structure.
 135 .Sh RETURN VALUES
 136 Upon successful completion,
 137 the number of bytes which were sent is returned.
 138 Otherwise, -1 is returned and the global variable
 139 .Va errno
 140 is set to indicate the error.
 141 .Sh ERRORS
 142 The
 143 .Fn send ,
 144 .Fn sendmsg ,
 145 and
 146 .Fn sendto
 147 system calls will fail if:
 148 .Bl -tag -width Er
 149 .\" ===========
 150 .It Bq Er EACCES
 151 The SO_BROADCAST option is not set on the socket
 152 and a broadcast address is given as the destination.
 153 .\" ===========
 154 .It Bq Er EAGAIN
 155 The socket is marked non-blocking
 156 and the requested operation would block.
 157 .\" ===========
 158 .It Bq Er EBADF
 159 An invalid descriptor is specified.
 160 .\" ===========
 161 .It Bq Er ECONNRESET
 162 A connection is forcibly closed by a peer.
 163 .\" ===========
 164 .It Bq Er EFAULT
 165 An invalid user space address is specified for a parameter.
 166 .\" ===========
 167 .It Bq Er EHOSTUNREACH
 168 The destination address specifies an unreachable host.
 169 .\" ===========
 170 .It Bq Er EINTR
 171 A signal interrupts the system call
 172 before any data is transmitted.
 173 .\" ===========
 174 .It Bq Er EMSGSIZE
 175 The socket requires that message be sent atomically,
 176 and the size of the message to be sent makes this impossible.
 177 .\" ===========
 178 .It Bq Er ENETDOWN
 179 The local network interface used to reach the destination is down.
 180 .\" ===========
 181 .It Bq Er ENETUNREACH
 182 No route to the network is present.
 183 .\" ===========
 184 .It Bq Er ENOBUFS
 185 The system is unable to allocate an internal buffer.
 186 The operation may succeed when buffers become available.
 187 .\" ===========
 188 .It Bq Er ENOBUFS
 189 The output queue for a network interface is full.
 190 This generally indicates that the interface has stopped sending,
 191 but may be caused by transient congestion.
 192 .\" ===========
 193 .It Bq Er ENOTSOCK
 194 The argument
 195 .Fa socket
 196 is not a socket.
 197 .\" ===========
 198 .It Bq Er EOPNOTSUPP
 199 .Fa socket
 200 does not support (some of) the option(s) specified in
 201 .Fa flags .
 202 .\" ===========
 203 .It Bq Er EPIPE
 204 The socket is shut down for writing
 205 or the socket is connection-mode and is no longer connected.
 206 In the latter case, and if the socket is of type SOCK_STREAM,
 207 the SIGPIPE signal is generated to the calling thread.
 208 .El
 209 .Pp
 210 The
 211 .Fn sendmsg
 212 and
 213 .Fn sendto
 214 system calls will fail if:
 215 .Bl -tag -width Er
 216 .\" ===========
 217 .It Bq Er EAFNOSUPPORT
 218 Addresses in the specified address family cannot be used
 219 with this socket.
 220 .\" ===========
 221 .It Bq Er EDESTADDRREQ
 222 The socket is not connection-mode and does not have its peer address set,
 223 and no destination address is specified.
 224 .\" ===========
 225 .It Bq Er EISCONN
 226 A destination address was specified and the socket is already connected.
 227 .\" ===========
 228 .It Bq Er ENOENT
 229 A component of the pathname does not name an existing file
 230 or the path name is an empty string.
 231 .\" ===========
 232 .It Bq Er ENOMEM
 233 Insufficient memory is available to fulfill the request.
 234 .\" ===========
 235 .It Bq Er ENOTCONN
 236 The socket is connection-mode, but is not connected.
 237 .\" ===========
 238 .It Bq Er ENOTDIR
 239 A component of the path prefix of the pathname in the socket address
 240 is not a directory.
 241 .El
 242 .Pp
 243 The
 244 .Fn send
 245 system call will fail if:
 246 .Bl -tag -width Er
 247 .\" ===========
 248 .It Bq Er EDESTADDRREQ
 249 The socket is not connection-mode and no peer address is set.
 250 .\" ===========
 251 .It Bq Er ENOTCONN
 252 The socket is not connected or otherwise has not had the peer pre-specified.
 253 .El
 254 .Pp
 255 The
 256 .Fn sendmsg
 257 system call will fail if:
 258 .Bl -tag -width Er
 259 .\" ===========
 260 .It Bq Er EINVAL
 261 The sum of the iov_len values overflows an ssize_t.
 262 .El
 263 .Sh LEGACY SYNOPSIS
 264 .Fd #include <sys/types.h>
 265 .Fd #include <sys/socket.h>
 266 .Pp
 267 The include file
 268 .In sys/types.h is necessary.
 269 .Sh SEE ALSO
 270 .Xr fcntl 2 ,
 271 .Xr getsockopt 2 ,
 272 .Xr recv 2 ,
 273 .Xr select 2 ,
 274 .Xr socket 2 ,
 275 .Xr write 2 ,
 276 .Xr compat 5
 277 .Sh HISTORY
 278 The
 279 .Fn send
 280 function call appeared in
 281 .Bx 4.2 .