lib/libc/sys/send.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd April 27, 2020
  29 .Dt SEND 2
  30 .Os
  31 .Sh NAME
  32 .Nm send ,
  33 .Nm sendto ,
  34 .Nm sendmsg ,
  35 .Nm sendmmsg
  36 .Nd send message(s) from a socket
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/socket.h
  41 .Ft ssize_t
  42 .Fn send "int s" "const void *msg" "size_t len" "int flags"
  43 .Ft ssize_t
  44 .Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
  45 .Ft ssize_t
  46 .Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
  47 .Ft ssize_t
  48 .Fn sendmmsg "int s" "struct mmsghdr * restrict msgvec" "size_t vlen" "int flags"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn send
  52 and
  53 .Fn sendmmsg
  54 functions,
  55 and
  56 .Fn sendto
  57 and
  58 .Fn sendmsg
  59 system calls
  60 are used to transmit one or more messages (with the
  61 .Fn sendmmsg
  62 call) to
  63 another socket.
  64 The
  65 .Fn send
  66 function
  67 may be used only when the socket is in a
  68 .Em connected
  69 state.
  70 The functions
  71 .Fn sendto ,
  72 .Fn sendmsg
  73 and
  74 .Fn sendmmsg
  75 may be used at any time if the socket is connectionless-mode.
  76 If the socket is connection-mode, the protocol
  77 must support implied connect (currently
  78 .Xr tcp 4
  79 is the only protocol with support) or the socket must be in a
  80 connected state before use.
  81 .Pp
  82 The address of the target is given by
  83 .Fa to
  84 with
  85 .Fa tolen
  86 specifying its size, or the equivalent
  87 .Fa msg_name
  88 and
  89 .Fa msg_namelen
  90 in
  91 .Fa struct msghdr .
  92 If the socket is in a connected state, the target address passed to
  93 .Fn sendto ,
  94 .Fn sendmsg
  95 or
  96 .Fn sendmmsg
  97 is ignored.
  98 The length of the message is given by
  99 .Fa len .
 100 If the message is too long to pass atomically through the
 101 underlying protocol, the error
 102 .Er EMSGSIZE
 103 is returned, and
 104 the message is not transmitted.
 105 .Pp
 106 The
 107 .Fn sendmmsg
 108 function sends multiple messages at a call.
 109 They are given by the
 110 .Fa msgvec
 111 vector along with
 112 .Fa vlen
 113 specifying the vector size.
 114 The number of octets sent per each message is placed in the
 115 .Fa msg_len
 116 field of each processed element of the vector after transmission.
 117 .Pp
 118 No indication of failure to deliver is implicit in a
 119 .Fn send .
 120 Locally detected errors are indicated by a return value of -1.
 121 .Pp
 122 If no messages space is available at the socket to hold
 123 the message to be transmitted, then
 124 .Fn send
 125 normally blocks, unless the socket has been placed in
 126 non-blocking I/O mode.
 127 The
 128 .Xr select 2
 129 system call may be used to determine when it is possible to
 130 send more data.
 131 .Pp
 132 The
 133 .Fa flags
 134 argument may include one or more of the following:
 135 .Bd -literal
 136 #define MSG_OOB         0x00001 /* process out-of-band data */
 137 #define MSG_DONTROUTE   0x00004 /* bypass routing, use direct interface */
 138 #define MSG_EOR         0x00008 /* data completes record */
 139 #define MSG_DONTWAIT    0x00080 /* do not block */
 140 #define MSG_EOF         0x00100 /* data completes transaction */
 141 #define MSG_NOSIGNAL    0x20000 /* do not generate SIGPIPE on EOF */
 142 .Ed
 143 .Pp
 144 The flag
 145 .Dv MSG_OOB
 146 is used to send
 147 .Dq out-of-band
 148 data on sockets that support this notion (e.g.\&
 149 .Dv SOCK_STREAM ) ;
 150 the underlying protocol must also support
 151 .Dq out-of-band
 152 data.
 153 .Dv MSG_EOR
 154 is used to indicate a record mark for protocols which support the
 155 concept.
 156 The
 157 .Dv MSG_DONTWAIT
 158 flag request the call to return when it would block otherwise.
 159 .Dv MSG_EOF
 160 requests that the sender side of a socket be shut down, and that an
 161 appropriate indication be sent at the end of the specified data;
 162 this flag is only implemented for
 163 .Dv SOCK_STREAM
 164 sockets in the
 165 .Dv PF_INET
 166 protocol family.
 167 .Dv MSG_DONTROUTE
 168 is usually used only by diagnostic or routing programs.
 169 .Dv MSG_NOSIGNAL
 170 is used to prevent
 171 .Dv SIGPIPE
 172 generation when writing a socket that
 173 may be closed.
 174 .Pp
 175 See
 176 .Xr recv 2
 177 for a description of the
 178 .Fa msghdr
 179 structure and the
 180 .Fa mmsghdr
 181 structure.
 182 .Sh RETURN VALUES
 183 The
 184 .Fn send ,
 185 .Fn sendto
 186 and
 187 .Fn sendmsg
 188 calls
 189 return the number of octets sent.
 190 The
 191 .Fn sendmmsg
 192 call returns the number of messages sent.
 193 If an error occurred a value of -1 is returned.
 194 .Sh ERRORS
 195 The
 196 .Fn send
 197 and
 198 .Fn sendmmsg
 199 functions and
 200 .Fn sendto
 201 and
 202 .Fn sendmsg
 203 system calls
 204 fail if:
 205 .Bl -tag -width Er
 206 .It Bq Er EBADF
 207 An invalid descriptor was specified.
 208 .It Bq Er EACCES
 209 The destination address is a broadcast address, and
 210 .Dv SO_BROADCAST
 211 has not been set on the socket.
 212 .It Bq Er ENOTCONN
 213 The socket is connection-mode but is not connected.
 214 .It Bq Er ENOTSOCK
 215 The argument
 216 .Fa s
 217 is not a socket.
 218 .It Bq Er EFAULT
 219 An invalid user space address was specified for an argument.
 220 .It Bq Er EMSGSIZE
 221 The socket requires that message be sent atomically,
 222 and the size of the message to be sent made this impossible.
 223 .It Bq Er EAGAIN
 224 The socket is marked non-blocking, or
 225 .Dv MSG_DONTWAIT
 226 is specified, and the requested operation would block.
 227 .It Bq Er ENOBUFS
 228 The system was unable to allocate an internal buffer.
 229 The operation may succeed when buffers become available.
 230 .It Bq Er ENOBUFS
 231 The output queue for a network interface was full.
 232 This generally indicates that the interface has stopped sending,
 233 but may be caused by transient congestion.
 234 .It Bq Er EHOSTUNREACH
 235 The remote host was unreachable.
 236 .It Bq Er EISCONN
 237 A destination address was specified and the socket is already connected.
 238 .It Bq Er ECONNREFUSED
 239 The socket received an ICMP destination unreachable message
 240 from the last message sent.
 241 This typically means that the
 242 receiver is not listening on the remote port.
 243 .It Bq Er EHOSTDOWN
 244 The remote host was down.
 245 .It Bq Er ENETDOWN
 246 The remote network was down.
 247 .It Bq Er EADDRNOTAVAIL
 248 The process using a
 249 .Dv SOCK_RAW
 250 socket was jailed and the source
 251 address specified in the IP header did not match the IP
 252 address bound to the prison.
 253 .It Bq Er EPIPE
 254 The socket is unable to send anymore data
 255 .Dv ( SBS_CANTSENDMORE
 256 has been set on the socket).
 257 This typically means that the socket
 258 is not connected.
 259 .El
 260 .Sh SEE ALSO
 261 .Xr connect 2 ,
 262 .Xr fcntl 2 ,
 263 .Xr getsockopt 2 ,
 264 .Xr recv 2 ,
 265 .Xr select 2 ,
 266 .Xr socket 2 ,
 267 .Xr write 2 ,
 268 .Xr CMSG_DATA 3
 269 .Sh HISTORY
 270 The
 271 .Fn send
 272 function appeared in
 273 .Bx 4.2 .
 274 The
 275 .Fn sendmmsg
 276 function appeared in
 277 .Fx 11.0 .
 278 .Sh BUGS
 279 Because
 280 .Fn sendmsg
 281 does not necessarily block until the data has been transferred, it
 282 is possible to transfer an open file descriptor across an
 283 .Dv AF_UNIX
 284 domain socket
 285 (see
 286 .Xr recv 2 ) ,
 287 then
 288 .Fn close
 289 it before it has actually been sent, the result being that the receiver
 290 gets a closed file descriptor.
 291 It is left to the application to
 292 implement an acknowledgment mechanism to prevent this from happening.