bsd/man/man2/connectx.2

   1 .\"
   2 .\" Copyright (c) 2015 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. The rights granted to you under the License
  10 .\" may not be used to create, or enable the creation or redistribution of,
  11 .\" unlawful or unlicensed copies of an Apple operating system, or to
  12 .\" circumvent, violate, or enable the circumvention or violation of, any
  13 .\" terms of an Apple operating system software license agreement.
  14 .\"
  15 .\" Please obtain a copy of the License at
  16 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
  17 .\"
  18 .\" The Original Code and all software distributed under the License are
  19 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23 .\" Please see the License for the specific language governing rights and
  24 .\" limitations under the License.
  25 .\"
  26 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27 .\"
  28 .Dd March 26, 2015
  29 .Dt CONNECTX 2
  30 .Os Darwin
  31 .Sh NAME
  32 .Nm connectx
  33 .Nd initiate a connection on a socket
  34 .Sh SYNOPSIS
  35 .Fd #include <sys/socket.h>
  36 .Ft int
  37 .Fo connectx
  38 .Fa "int socket"
  39 .Fa "const sa_endpoints_t *endpoints"
  40 .Fa "sae_associd_t associd"
  41 .Fa "unsigned int flags"
  42 .Fa "const struct iovec *iov"
  43 .Fa "unsigned int iovcnt"
  44 .Fa "size_t *len"
  45 .Fa "sae_connid_t *connid"
  46 .Fc
  47 .Sh DESCRIPTION
  48 The parameter
  49 .Fa socket
  50 is a socket.
  51 In general,
  52 .Fn connectx
  53 may be used as a substitute for cases when
  54 .Xr bind 2
  55 and
  56 .Xr connect 2
  57 are issued in succession, as well as a mechanism to transmit data
  58 at connection establishment time.
  59 .Pp
  60 The
  61 .Fn connectx
  62 system call uses a
  63 .Fa sa_endpoints
  64 structure to minimize the number of directly supplied arguments. This structure
  65 has the following form, as defined in
  66 .In sys/socket.h :
  67 .Pp
  68 .Bd -literal
  69 typedef struct sa_endpoints {
  70         unsigned int     sae_srcif;      /* optional source interface   */
  71         struct sockaddr *sae_srcaddr;    /* optional source address     */
  72         socklen_t        sae_srcaddrlen; /* size of source address      */
  73         struct sockaddr *sae_dstaddr;    /* destination address         */
  74         socklen_t        sae_dstaddrlen; /* size of destination address */
  75 }sa_endpoints_t;
  76 .Ed
  77 .Pp
  78 When the optional source address
  79 .Fa sae_srcaddr
  80 parameter is specified,
  81 .Fn connectx
  82 binds the connection to the address, as if
  83 .Xr bind 2
  84 is used.  The length of
  85 .Fa sae_srcaddr
  86 buffer is specified by
  87 .Fa sae_srcaddrlen .
  88 .\" This buffer may hold more than one addresses, where each successive address
  89 .\" immediately follows the previous one.
  90 The source address can be obtained by calling
  91 .Xr getifaddrs 3 .
  92 .Pp
  93 The optional parameter
  94 .Fa sae_srcif
  95 may also be specified, in order to force the connection to use the interface
  96 whose interface index equals to
  97 .Fa sae_srcif .
  98 The value for
  99 .Fa sae_srcif
 100 may be obtained by issuing a call to
 101 .Xr if_nametoindex 3 .
 102 If only
 103 .Fa sae_srcif
 104 is specified, the communication domain will choose a source address on that
 105 interface for communicating to the peer socket.  Both
 106 .Fa sae_srcaddr
 107 and
 108 .Fa sae_srcif
 109 parameters may also be specified in order to add more constraints to the connection, and
 110 .Fn connectx
 111 will fail unless the address is currently assigned to that interface.
 112 .Pp
 113 A destination address must be specified in the
 114 .Fa sae_dstaddr
 115 parameter.  The
 116 .Fa sae_dstaddrlen
 117 specifies the length of that buffer.
 118 .\" When more than one addresses
 119 .\" is specified, each successive address immediately follows the previous one.
 120 .\" Each communication domain interprets the
 121 .\" .Fa sae_srcaddr
 122 .\" and
 123 .\" .Fa sae_dstaddr
 124 .\" parameters in its own way.
 125 .\" When multiple addresses are specified, one of the addresses will be chosen.
 126 .\" The rules used in selecting the eligible addresses as well as their address family requirements vary between communication domains.
 127 .\" .Pp
 128 .\" Changes related to the connection state may be monitored by registering for the
 129 .\" .Dv NOTE_CONNINFO_UPDATED
 130 .\" .Xr kqueue 2
 131 .\" event, using the predefined system filter
 132 .\" .Dv EVFILT_SOCK .
 133 .\" Details regarding the event may be retrieved by calling
 134 .\" .Xr getconninfo 3 .
 135 .\" .Sh MULTIPATH
 136 .\" On a multipath socket,
 137 .\" .Fn connectx
 138 .\" may be used multiple times, in order to establish the initial session
 139 .\" association with the peer socket upon the first connection, and to further
 140 .\" establish additional connections related to that association on subsequent
 141 .\" ones.
 142 .\" .Pp
 143 .\" The parameter
 144 .\" .Fa associd
 145 .\" specifies the association identifier.  When
 146 .\" .Fn connectx
 147 .\" is initially called to establish an associtation, the association identifier
 148 .\" is not yet known, and
 149 .\" .Dv ASSOCID_ANY
 150 .\" must be specified.  After the initial connection is established, the
 151 .\" association identifier may be retrieved using
 152 .\" .Xr getassocids 3 ,
 153 .\" and the value may then be used on subsequent
 154 .\" .Fn connectx
 155 .\" calls.
 156 .\" .Pp
 157 .\" An association representing one or more connections, or a single connection
 158 .\" may be dissolved by calling
 159 .\" .Xr disconnectx 2 .
 160 .\" .Sh NON-MULTIPATH
 161 .\" On non-multipath socket,
 162 .\" .Fn connectx
 163 .\" behaves much like a combination of
 164 .\" .Xr bind 2
 165 .\" and
 166 .\" .Xr connect 2 .
 167 .Pp
 168 Data to be transmitted may optionally be defined via the
 169 .Fa iovcnt
 170 buffers specified by members of the
 171 .Fa iov
 172 array, along with a non-NULL
 173 .Fa len
 174 parameter, which upon success, indicates the number of bytes enqueued for
 175 transmission.
 176 .Pp
 177 When the
 178 .Fa iov
 179 and
 180 .Fa len
 181 parameters are non-NULL, the communication domain will copy the data to the
 182 socket send buffer. The communication domain may impose a limit on the amount of data allowed to be buffered before connection establishment.
 183 .Pp
 184 When the flags parameter is set to CONNECT_RESUME_ON_READ_WRITE and an
 185 .Fa iov
 186 is not passed in, the communication domain will trigger the actual connection
 187 establishment upon the first read or write following the
 188 .Xr connectx 2
 189 system call. This flag is ignored if the iov is specified in the
 190 .Xr connectx 2
 191 call itself.
 192 .Pp
 193 The flags parameter may also be set to CONNECT_DATA_IDEMPOTENT to indicate to
 194 the communication domain that the data is idempotent. For example, this will
 195 trigger TCP Fast Open (RFC 7413) with SOCK_STREAM type. The data must be passed in the
 196 .Fa iov
 197 parameter in
 198 .Xr connectx 2
 199 , or passed in with the first write call such as with the
 200 .Xr writev 2
 201 or similar system call if the CONNECT_RESUME_ON_READ_WRITE is also set.
 202 .Pp
 203 In general, the communication domain makes the final decision on the amount of
 204 data that may get transmitted at connection establishment time.  If the socket
 205 requires the data be sent atomically and the data size makes this impossible,
 206 EMSGSIZE will be returned and the state of the socket is left unchanged as if
 207 .Fn connectx
 208 was not called.
 209 .Pp
 210 The parameter
 211 .Fa associd
 212 is reserved for future use, and must always be set to
 213 .Dv SAE_ASSOCID_ANY .
 214 The parameter
 215 .Fa connid
 216 is also reserved for future use and should be set to NULL.
 217 .Sh NOTES
 218 .Fn connectx
 219 is currently supported only on AF_INET and AF_INET6 sockets of type SOCK_DGRAM
 220 and SOCK_STREAM.
 221 .Pp
 222 Generally,
 223 .\" non-multipath
 224 connection-oriented sockets may successfully
 225 .Fn connectx
 226 only once.  Connectionless sockets may use
 227 .Fn connectx
 228 to create an association to the peer socket, and it may call
 229 .Xr disconnectx 2
 230 to dissolve any existing association.  Unlike connection-oriented sockets,
 231 connectionless sockets may call
 232 .Fn connectx
 233 again afterwards to associate to another peer socket.
 234 .Pp
 235 If CONNECT_RESUME_ON_READ_WRITE is set without data
 236 supplied,
 237 .Fn connectx
 238 will immediately return success, assuming the rest of the parameters are valid.
 239 .Xr select 2
 240 will indicate that the socket is ready for writing, and the actual connection
 241 establishment is attempted once the initial data is written to the socket via
 242 .Xr writev 2
 243 or similar.  Subsequent attempts to write more data will fail until the existing
 244 connection establishment attempt is successful.  The error status of the socket
 245 may be retrieved via the SO_ERROR option using
 246 .Xr getsockopt 2 .
 247 .Sh RETURN VALUES
 248 Upon successful completion, a value of 0 is returned.
 249 .\" and an opaque value may be returned through the
 250 .\" .Fa connid
 251 .\" parameter.
 252 The number of bytes from
 253 .Fa iov
 254 array which were enqueued for transmission is returned via
 255 .Fa len .
 256 .\" If the initial connection establishes an association with a peer socket, the association identifier may be retrieved by calling
 257 .\" .Xr getassocids 2 .
 258 .\" Both of these identifiers are unique
 259 .\" on a per
 260 .\" .Fa socket
 261 .\" basis.
 262 Upon failure, a value of -1 is returned and the global integer
 263 variable
 264 .Va errno
 265 is set to indicate the error.
 266 .Sh ERRORS
 267 The
 268 .Fn connectx
 269 system call will fail if:
 270 .Bl -tag -width Er
 271 .\" ==========
 272 .It Bq Er EADDRINUSE
 273 The address specified in
 274 .Fa sae_srcaddr
 275 parameter is already in use.
 276 .\" ==========
 277 .It Bq Er EADDRNOTAVAIL
 278 The specified in
 279 .Fa sae_srcaddr
 280 parameter is not available on this machine, or is not assigned to the interface specified by
 281 .Fa sae_srcif .
 282 .\" ==========
 283 .It Bq Er EAFNOSUPPORT
 284 The
 285 .Fa socket
 286 cannot find any usable addresses of a specific address family
 287 as required by the communication domain.
 288 .\" ==========
 289 .It Bq Er EALREADY
 290 A previous connection attempt has not yet been completed.
 291 .\" ==========
 292 .It Bq Er EBADF
 293 .Fa socket
 294 is not a valid descriptor.
 295 .\" ==========
 296 .It Bq Er ECONNREFUSED
 297 The attempt to connect was ignored
 298 (because the target is not listening for connections)
 299 or explicitly rejected.
 300 .\" ==========
 301 .It Bq Er EFAULT
 302 Part of
 303 .Fa iov
 304 or data to be written to
 305 .Fa socket
 306 points outside the process's allocated address space.
 307 .\" ==========
 308 .It Bq Er EHOSTUNREACH
 309 The target host cannot be reached (e.g., down, disconnected).
 310 .\" ==========
 311 .It Bq Er EINPROGRESS
 312 The connection cannot be completed immediately.
 313 It is possible to
 314 .Xr select 2
 315 for completion by selecting the
 316 .Fa socket
 317 for writing.
 318 .\" ==========
 319 .It Bq Er EINTR
 320 Its execution was interrupted by a signal.
 321 .\" ==========
 322 .It Bq Er EMSGSIZE
 323 The size of the message exceeds the available send buffer space in the
 324 .Fa socket .
 325 .\" ==========
 326 .It Bq Er EINVAL
 327 An invalid argument was detected
 328 (e.g.,
 329 .Fa sae_dstaddrlen
 330 is not valid, the contents of
 331 .Fa sae_srcaddr
 332 or
 333 .Fa sae_dstaddr,
 334 buffer is invalid, etc.)
 335 .\" ==========
 336 .It Bq Er EISCONN
 337 The socket is already connected.
 338 .\" ==========
 339 .It Bq Er ENETDOWN
 340 The local network interface is not functioning.
 341 .\" ==========
 342 .It Bq Er ENETUNREACH
 343 The network isn't reachable from this host.
 344 .\" ==========
 345 .It Bq Er ENOBUFS
 346 The system call was unable to allocate a needed memory buffer.
 347 .\" ==========
 348 .It Bq Er ENOTSOCK
 349 .Fa socket
 350 is not a file descriptor for a socket.
 351 .\" ==========
 352 .It Bq Er EOPNOTSUPP
 353 Because
 354 .Fa socket
 355 is listening, no connection is allowed.
 356 .\" ==========
 357 .\".It Bq Er EPROTOTYPE
 358 .\".Fa address
 359 .\"has a different type than the socket
 360 .\"that is bound to the specified peer address.
 361 .\" ==========
 362 .It Bq Er ETIMEDOUT
 363 Connection establishment timed out without establishing a connection.
 364 .\" ==========
 365 .El
 366 .Sh SEE ALSO
 367 .\".Xr accept 2 ,
 368 .Xr bind 2 ,
 369 .Xr connect 2 ,
 370 .Xr disconnectx 2 ,
 371 .Xr disconnectx 2 ,
 372 .Xr getsockopt 2 ,
 373 .\".Xr kqueue 2 ,
 374 .\".Xr shutdown 2 ,
 375 .Xr select 2 ,
 376 .Xr socket 2 ,
 377 .\".Xr getassocids 3 ,
 378 .\".Xr getconnids 3 ,
 379 .\".Xr getconninfo 3 ,
 380 .Xr writev 2 ,
 381 .Xr compat 5
 382 .Sh HISTORY
 383 The
 384 .Fn connectx
 385 function call appeared in Darwin 15.0.0