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 .\" If the initial connection is established without any protocol-level
 158 .\" multipath association, the error
 159 .\" .Er EPROTO
 160 .\" will be returned, and the connection can be extracted to a new socket with
 161 .\" the same properties of
 162 .\" .Fa socket ,
 163 .\" by calling
 164 .\" .Xr peeloff 2 .
 165 .\" .Pp
 166 .\" An association representing one or more connections, or a single connection
 167 .\" may be dissolved by calling
 168 .\" .Xr disconnectx 2 .
 169 .\" .Sh NON-MULTIPATH
 170 .\" On non-multipath socket,
 171 .\" .Fn connectx
 172 .\" behaves much like a combination of
 173 .\" .Xr bind 2
 174 .\" and
 175 .\" .Xr connect 2 .
 176 .Pp
 177 Data to be transmitted may optionally be defined via the
 178 .Fa iovcnt
 179 buffers specified by members of the
 180 .Fa iov
 181 array, along with a non-NULL
 182 .Fa len
 183 parameter, which upon success, indicates the number of bytes enqueued for
 184 transmission.
 185 .Pp
 186 When the
 187 .Fa iov
 188 and
 189 .Fa len
 190 parameters are non-NULL, the communication domain will copy the data to the
 191 socket send buffer. The communication domain may impose a limit on the amount of data allowed to be buffered before connection establishment.
 192 .Pp
 193 When the flags parameter is set to CONNECT_RESUME_ON_READ_WRITE and an
 194 .Fa iov
 195 is not passed in, the communication domain will trigger the actual connection
 196 establishment upon the first read or write following the
 197 .Xr connectx 2
 198 system call. This flag is ignored if the iov is specified in the
 199 .Xr connectx 2
 200 call itself.
 201 .Pp
 202 The flags parameter may also be set to CONNECT_DATA_IDEMPOTENT to indicate to
 203 the communication domain that the data is idempotent. For example, this will
 204 trigger TCP Fast Open (RFC 7413) with SOCK_STREAM type. The data must be passed in the
 205 .Fa iov
 206 parameter in
 207 .Xr connectx 2
 208 , or passed in with the first write call such as with the
 209 .Xr writev 2
 210 or similar system call if the CONNECT_RESUME_ON_READ_WRITE is also set.
 211 .Pp
 212 In general, the communication domain makes the final decision on the amount of
 213 data that may get transmitted at connection establishment time.  If the socket
 214 requires the data be sent atomically and the data size makes this impossible,
 215 EMSGSIZE will be returned and the state of the socket is left unchanged as if
 216 .Fn connectx
 217 was not called.
 218 .Pp
 219 The parameter
 220 .Fa associd
 221 is reserved for future use, and must always be set to
 222 .Dv SAE_ASSOCID_ANY .
 223 The parameter
 224 .Fa connid
 225 is also reserved for future use and should be set to NULL.
 226 .Sh NOTES
 227 .Fn connectx
 228 is currently supported only on AF_INET and AF_INET6 sockets of type SOCK_DGRAM
 229 and SOCK_STREAM.
 230 .Pp
 231 Generally,
 232 .\" non-multipath
 233 connection-oriented sockets may successfully
 234 .Fn connectx
 235 only once.  Connectionless sockets may use
 236 .Fn connectx
 237 to create an association to the peer socket, and it may call
 238 .Xr disconnectx 2
 239 to dissolve any existing association.  Unlike connection-oriented sockets,
 240 connectionless sockets may call
 241 .Fn connectx
 242 again afterwards to associate to another peer socket.
 243 .Pp
 244 If CONNECT_RESUME_ON_READ_WRITE is set without data
 245 supplied,
 246 .Fn connectx
 247 will immediately return success, assuming the rest of the parameters are valid.
 248 .Xr select 2
 249 will indicate that the socket is ready for writing, and the actual connection
 250 establishment is attempted once the initial data is written to the socket via
 251 .Xr writev 2
 252 or similar.  Subsequent attempts to write more data will fail until the existing
 253 connection establishment attempt is successful.  The error status of the socket
 254 may be retrieved via the SO_ERROR option using
 255 .Xr getsockopt 2 .
 256 .Sh RETURN VALUES
 257 Upon successful completion, a value of 0 is returned.
 258 .\" and an opaque value may be returned through the
 259 .\" .Fa connid
 260 .\" parameter.
 261 The number of bytes from
 262 .Fa iov
 263 array which were enqueued for transmission is returned via
 264 .Fa len .
 265 .\" If the initial connection establishes an association with a peer socket, the association identifier may be retrieved by calling
 266 .\" .Xr getassocids 2 .
 267 .\" Both of these identifiers are unique
 268 .\" on a per
 269 .\" .Fa socket
 270 .\" basis.
 271 Upon failure, a value of -1 is returned and the global integer
 272 variable
 273 .Va errno
 274 is set to indicate the error.
 275 .Sh ERRORS
 276 The
 277 .Fn connectx
 278 system call will fail if:
 279 .Bl -tag -width Er
 280 .\" ==========
 281 .It Bq Er EADDRINUSE
 282 The address specified in
 283 .Fa sae_srcaddr
 284 parameter is already in use.
 285 .\" ==========
 286 .It Bq Er EADDRNOTAVAIL
 287 The specified in
 288 .Fa sae_srcaddr
 289 parameter is not available on this machine, or is not assigned to the interface specified by
 290 .Fa sae_srcif .
 291 .\" ==========
 292 .It Bq Er EAFNOSUPPORT
 293 The
 294 .Fa socket
 295 cannot find any usable addresses of a specific address family
 296 as required by the communication domain.
 297 .\" ==========
 298 .It Bq Er EALREADY
 299 A previous connection attempt has not yet been completed.
 300 .\" ==========
 301 .It Bq Er EBADF
 302 .Fa socket
 303 is not a valid descriptor.
 304 .\" ==========
 305 .It Bq Er ECONNREFUSED
 306 The attempt to connect was ignored
 307 (because the target is not listening for connections)
 308 or explicitly rejected.
 309 .\" ==========
 310 .It Bq Er EFAULT
 311 Part of
 312 .Fa iov
 313 or data to be written to
 314 .Fa socket
 315 points outside the process's allocated address space.
 316 .\" ==========
 317 .It Bq Er EHOSTUNREACH
 318 The target host cannot be reached (e.g., down, disconnected).
 319 .\" ==========
 320 .It Bq Er EINPROGRESS
 321 The connection cannot be completed immediately.
 322 It is possible to
 323 .Xr select 2
 324 for completion by selecting the
 325 .Fa socket
 326 for writing.
 327 .\" ==========
 328 .It Bq Er EINTR
 329 Its execution was interrupted by a signal.
 330 .\" ==========
 331 .It Bq Er EMSGSIZE
 332 The size of the message exceeds the available send buffer space in the
 333 .Fa socket .
 334 .\" ==========
 335 .It Bq Er EINVAL
 336 An invalid argument was detected
 337 (e.g.,
 338 .Fa sae_dstaddrlen
 339 is not valid, the contents of
 340 .Fa sae_srcaddr
 341 or
 342 .Fa sae_dstaddr,
 343 buffer is invalid, etc.)
 344 .\" ==========
 345 .It Bq Er EISCONN
 346 The socket is already connected.
 347 .\" ==========
 348 .It Bq Er ENETDOWN
 349 The local network interface is not functioning.
 350 .\" ==========
 351 .It Bq Er ENETUNREACH
 352 The network isn't reachable from this host.
 353 .\" ==========
 354 .It Bq Er ENOBUFS
 355 The system call was unable to allocate a needed memory buffer.
 356 .\" ==========
 357 .It Bq Er ENOTSOCK
 358 .Fa socket
 359 is not a file descriptor for a socket.
 360 .\" ==========
 361 .It Bq Er EOPNOTSUPP
 362 Because
 363 .Fa socket
 364 is listening, no connection is allowed.
 365 .\" ==========
 366 .\".It Bq Er EPROTO
 367 .\"The connection was successfully established without any protocol-level
 368 .\"association.  The connection can be extracted to a new socket using
 369 .\".Xr peeloff 2 .
 370 .\" ==========
 371 .\".It Bq Er EPROTOTYPE
 372 .\".Fa address
 373 .\"has a different type than the socket
 374 .\"that is bound to the specified peer address.
 375 .\" ==========
 376 .It Bq Er ETIMEDOUT
 377 Connection establishment timed out without establishing a connection.
 378 .\" ==========
 379 .El
 380 .Sh SEE ALSO
 381 .\".Xr accept 2 ,
 382 .Xr bind 2 ,
 383 .Xr connect 2 ,
 384 .Xr disconnectx 2 ,
 385 .Xr disconnectx 2 ,
 386 .Xr getsockopt 2 ,
 387 .\".Xr kqueue 2 ,
 388 .\".Xr peeloff 2 ,
 389 .\".Xr shutdown 2 ,
 390 .Xr select 2 ,
 391 .Xr socket 2 ,
 392 .\".Xr getassocids 3 ,
 393 .\".Xr getconnids 3 ,
 394 .\".Xr getconninfo 3 ,
 395 .Xr writev 2 ,
 396 .Xr compat 5
 397 .Sh HISTORY
 398 The
 399 .Fn connectx
 400 function call appeared in Darwin 15.0.0