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