1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright 1989 AT&T
  19 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
  20 .\" Copyright 2018 Nexenta Systems, Inc.
  21 .\"
  22 .Dd August 2, 2018
  23 .Dt SEND 3C
  24 .Os
  25 .Sh NAME
  26 .Nm send ,
  27 .Nm sendto ,
  28 .Nm sendmsg
  29 .Nd send a message from a socket
  30 .Sh LIBRARY
  31 .Lb libc
  32 .Sh SYNOPSIS
  33 .In sys/types.h
  34 .In sys/socket.h
  35 .Ft ssize_t
  36 .Fo send
  37 .Fa "int s"
  38 .Fa "const void *msg"
  39 .Fa "size_t len"
  40 .Fa "int flags"
  41 .Fc
  42 .Ft ssize_t
  43 .Fo sendto
  44 .Fa "int s"
  45 .Fa "const void *msg"
  46 .Fa "size_t len"
  47 .Fa "int flags"
  48 .Fa "const struct sockaddr *to"
  49 .Fa "socklen_t tolen"
  50 .Fc
  51 .Ft ssize_t
  52 .Fo sendmsg
  53 .Fa "int s"
  54 .Fa "const struct msghdr *msg"
  55 .Fa "int flags"
  56 .Fc
  57 .Sh DESCRIPTION
  58 The
  59 .Fn send ,
  60 .Fn sendto ,
  61 and
  62 .Fn sendmsg
  63 functions are used to transmit a message to another transport end-point.
  64 The
  65 .Fn send
  66 function can be used only when the socket is in a connected state.
  67 See
  68 .Xr connect 3C .
  69 The
  70 .Fn sendto
  71 and
  72 .Fn sendmsg
  73 functions can be used at any time.
  74 The
  75 .Fa s
  76 socket is created with
  77 .Xr socket 3C .
  78 .Pp
  79 The address of the target is supplied by
  80 .Fa to
  81 with a
  82 .Fa tolen
  83 parameter used to specify the size.
  84 The length of the message is supplied by the
  85 .Fa len
  86 parameter.
  87 For socket types such as
  88 .Dv SOCK_DGRAM
  89 and
  90 .Dv SOCK_RAW
  91 that require atomic messages, the error
  92 .Er EMSGSIZE
  93 is returned and the message is not transmitted when it is too long to pass
  94 atomically through the underlying protocol.
  95 The same restrictions do not apply to
  96 .Dv SOCK_STREAM
  97 sockets.
  98 .Pp
  99 A return value -1 indicates locally detected errors.
 100 It does not imply a delivery failure.
 101 .Pp
 102 If the socket does not have enough buffer space available to hold a message,
 103 the
 104 .Fn send
 105 function blocks the message, unless the socket has been placed in non-blocking
 106 I/O mode
 107 .Po see
 108 .Xr fcntl 2
 109 .Pc .
 110 The
 111 .Xr select 3C
 112 or
 113 .Xr poll 2
 114 call can be used to determine when it is possible to send more data.
 115 .Pp
 116 The
 117 .Fa flags
 118 parameter is formed from the bitwise OR of zero or more of the following:
 119 .Bl -tag -width "MSG_DONTROUTE"
 120 .It Dv MSG_OOB
 121 Send out-of-band data on sockets that support this notion.
 122 The underlying protocol must also support out-of-band data.
 123 Only
 124 .Dv SOCK_STREAM
 125 sockets created in the
 126 .Dv AF_INET
 127 or the
 128 .Dv AF_INET6
 129 address family support out-of-band data.
 130 .It Dv MSG_DONTROUTE
 131 The
 132 .Dv SO_DONTROUTE
 133 option is turned on for the duration of the operation.
 134 It is used only by diagnostic or routing programs.
 135 .It Dv MSG_NOSIGNAL
 136 Don't generate the
 137 .Dv SIGPIPE
 138 signal when a stream-oriented socket is no longer connected.
 139 .El
 140 .Pp
 141 See
 142 .Xr recv 3C
 143 for a description of the
 144 .Va msghdr
 145 structure.
 146 .Sh RETURN VALUES
 147 Upon successful completion, these functions return the number of bytes sent.
 148 Otherwise, they return -1 and set
 149 .Va errno
 150 to indicate the error.
 151 .Sh ERRORS
 152 The
 153 .Fn send ,
 154 .Fn sendto ,
 155 and
 156 .Fn sendmsg
 157 functions return errors under the following conditions:
 158 .Bl -tag -width Er
 159 .It Bq Er EBADF
 160 .Fa s
 161 is not a valid file descriptor.
 162 .It Bq Er ECONNRESET
 163 The
 164 .Fa s
 165 argument refers to a connection oriented socket and the connection was forcibly
 166 closed by the peer and is no longer valid.
 167 I/O can no longer be performed to filedes.
 168 .It Bq Er EINTR
 169 The operation was interrupted by delivery of a signal before any data could be
 170 buffered to be sent.
 171 .It Bq Er EMSGSIZE
 172 The message is too large to be sent all at once (as the socket requires), or the
 173 .Va msg_iovlen
 174 member of the
 175 .Va msghdr
 176 structure pointed to by message is less than or equal to 0 or is greater than
 177 .Brq Dv IOV_MAX .
 178 .It Bq Er ENOMEM
 179 Insufficient memory is available to complete the operation.
 180 .It Bq Er ENOSR
 181 Insufficient STREAMS resources are available for the operation to complete.
 182 .It Bq Er ENOTSOCK
 183 .Fa s
 184 is not a socket.
 185 .It Bq Er EWOULDBLOCK
 186 The socket is marked non-blocking and the requested operation would block.
 187 .Er EWOULDBLOCK
 188 is also returned when sufficient memory is not immediately available to allocate
 189 a suitable buffer.
 190 In such a case, the operation can be retried later.
 191 .It Bq Er ECONNREFUSED
 192 The requested connection was refused by the peer.
 193 For connected IPv4 and IPv6 datagram sockets, this indicates that the system
 194 received an ICMP
 195 .Dq Destination Port Unreachable
 196 message from the peer in response to some prior transmission.
 197 .El
 198 .Pp
 199 The
 200 .Fn send
 201 and
 202 .Fn sendto
 203 functions return errors under the following conditions:
 204 .Bl -tag -width Er
 205 .It Bq Er EINVAL
 206 The
 207 .Fa len
 208 argument overflows a
 209 .Vt ssize_t .
 210 .Pp
 211 Inconsistent port attributes for system call.
 212 .El
 213 .Pp
 214 The
 215 .Fn sendto
 216 function returns errors under the following conditions:
 217 .Bl -tag -width Er
 218 .It Bq Er EINVAL
 219 The value specified for the
 220 .Fa tolen
 221 parameter is not the size of a valid address for the specified address family.
 222 .It Bq Er EISCON
 223 A destination address was specified and the socket is already connected.
 224 .El
 225 .Pp
 226 The
 227 .Fn sendmsg
 228 function returns errors under the following conditions:
 229 .Bl -tag -width Er
 230 .It Bq Er EINVAL
 231 The
 232 .Va msg_iovlen
 233 member of the
 234 .Va msghdr
 235 structure pointed to by
 236 .Fa msg
 237 is less than or equal to 0, or the sum of the
 238 .Va iov_len
 239 values in the
 240 .Va msg_iov
 241 array overflows a
 242 .Vt ssize_t .
 243 .Pp
 244 One of the
 245 .Va iov_len
 246 values in the
 247 .Va msg_iov
 248 array member of the
 249 .Va msghdr
 250 structure pointed to by
 251 .Fa msg
 252 is negative, or the sum of the
 253 .Va iov_len
 254 values in the
 255 .Va msg_iov
 256 array overflows a
 257 .Vt ssize_t .
 258 .Pp
 259 .Va msg_iov
 260 contents are inconsistent with port attributes.
 261 .El
 262 .Pp
 263 The
 264 .Fn send
 265 function returns errors under the following conditions:
 266 .Bl -tag -width Er
 267 .It Bq Er EPIPE
 268 The socket is shut down for writing, or the socket is connection-mode and is no
 269 longer connected.
 270 In the latter case, if the socket is of type
 271 .Dv SOCK_STREAM ,
 272 the
 273 .Dv SIGPIPE
 274 signal is generated to the calling thread unless the
 275 .Dv MSG_NOSIGNAL
 276 flag is set.
 277 .El
 278 .Sh MT-LEVEL
 279 .Sy Safe
 280 .Sh SEE ALSO
 281 .Xr fcntl 2 ,
 282 .Xr poll 2 ,
 283 .Xr write 2 ,
 284 .Xr connect 3C ,
 285 .Xr getsockopt 3C ,
 286 .Xr recv 3C ,
 287 .Xr select 3C ,
 288 .Xr sockaddr 3C ,
 289 .Xr socket 3C ,
 290 .Xr socket.h 3HEAD ,
 291 .Xr attributes 5