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 48The parameter 49.Fa socket 50is a socket. 51In general, 52.Fn connectx 53may be used as a substitute for cases when 54.Xr bind 2 55and 56.Xr connect 2 57are issued in succession, as well as a mechanism to transmit data 58at connection establishment time. 59.Pp 60The 61.Fn connectx 62system call uses a 63.Fa sa_endpoints 64structure to minimize the number of directly supplied arguments. This structure 65has the following form, as defined in 66.In sys/socket.h : 67.Pp 68.Bd -literal 69typedef 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 78When the optional source address 79.Fa sae_srcaddr 80parameter is specified, 81.Fn connectx 82binds the connection to the address, as if 83.Xr bind 2 84is used. The length of 85.Fa sae_srcaddr 86buffer 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. 90The source address can be obtained by calling 91.Xr getifaddrs 3 . 92.Pp 93The optional parameter 94.Fa sae_srcif 95may also be specified, in order to force the connection to use the interface 96whose interface index equals to 97.Fa sae_srcif . 98The value for 99.Fa sae_srcif 100may be obtained by issuing a call to 101.Xr if_nametoindex 3 . 102If only 103.Fa sae_srcif 104is specified, the communication domain will choose a source address on that 105interface for communicating to the peer socket. Both 106.Fa sae_srcaddr 107and 108.Fa sae_srcif 109parameters may also be specified in order to add more constraints to the connection, and 110.Fn connectx 111will fail unless the address is currently assigned to that interface. 112.Pp 113A destination address must be specified in the 114.Fa sae_dstaddr 115parameter. The 116.Fa sae_dstaddrlen 117specifies 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 168Data to be transmitted may optionally be defined via the 169.Fa iovcnt 170buffers specified by members of the 171.Fa iov 172array, along with a non-NULL 173.Fa len 174parameter, which upon success, indicates the number of bytes enqueued for 175transmission. 176.Pp 177When the 178.Fa iov 179and 180.Fa len 181parameters are non-NULL, the communication domain will copy the data to the 182socket send buffer. The communication domain may impose a limit on the amount of data allowed to be buffered before connection establishment. 183.Pp 184When the flags parameter is set to CONNECT_RESUME_ON_READ_WRITE and an 185.Fa iov 186is not passed in, the communication domain will trigger the actual connection 187establishment upon the first read or write following the 188.Xr connectx 2 189system call. This flag is ignored if the iov is specified in the 190.Xr connectx 2 191call itself. 192.Pp 193The flags parameter may also be set to CONNECT_DATA_IDEMPOTENT to indicate to 194the communication domain that the data is idempotent. For example, this will 195trigger TCP Fast Open (RFC 7413) with SOCK_STREAM type. The data must be passed in the 196.Fa iov 197parameter in 198.Xr connectx 2 199, or passed in with the first write call such as with the 200.Xr writev 2 201or similar system call if the CONNECT_RESUME_ON_READ_WRITE is also set. 202.Pp 203In general, the communication domain makes the final decision on the amount of 204data that may get transmitted at connection establishment time. If the socket 205requires the data be sent atomically and the data size makes this impossible, 206EMSGSIZE will be returned and the state of the socket is left unchanged as if 207.Fn connectx 208was not called. 209.Pp 210The parameter 211.Fa associd 212is reserved for future use, and must always be set to 213.Dv SAE_ASSOCID_ANY . 214The parameter 215.Fa connid 216is also reserved for future use and should be set to NULL. 217.Sh NOTES 218.Fn connectx 219is currently supported only on AF_INET and AF_INET6 sockets of type SOCK_DGRAM 220and SOCK_STREAM. 221.Pp 222Generally, 223.\" non-multipath 224connection-oriented sockets may successfully 225.Fn connectx 226only once. Connectionless sockets may use 227.Fn connectx 228to create an association to the peer socket, and it may call 229.Xr disconnectx 2 230to dissolve any existing association. Unlike connection-oriented sockets, 231connectionless sockets may call 232.Fn connectx 233again afterwards to associate to another peer socket. 234.Pp 235If CONNECT_RESUME_ON_READ_WRITE is set without data 236supplied, 237.Fn connectx 238will immediately return success, assuming the rest of the parameters are valid. 239.Xr select 2 240will indicate that the socket is ready for writing, and the actual connection 241establishment is attempted once the initial data is written to the socket via 242.Xr writev 2 243or similar. Subsequent attempts to write more data will fail until the existing 244connection establishment attempt is successful. The error status of the socket 245may be retrieved via the SO_ERROR option using 246.Xr getsockopt 2 . 247.Sh RETURN VALUES 248Upon successful completion, a value of 0 is returned. 249.\" and an opaque value may be returned through the 250.\" .Fa connid 251.\" parameter. 252The number of bytes from 253.Fa iov 254array 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. 262Upon failure, a value of -1 is returned and the global integer 263variable 264.Va errno 265is set to indicate the error. 266.Sh ERRORS 267The 268.Fn connectx 269system call will fail if: 270.Bl -tag -width Er 271.\" ========== 272.It Bq Er EADDRINUSE 273The address specified in 274.Fa sae_srcaddr 275parameter is already in use. 276.\" ========== 277.It Bq Er EADDRNOTAVAIL 278The specified in 279.Fa sae_srcaddr 280parameter 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 284The 285.Fa socket 286cannot find any usable addresses of a specific address family 287as required by the communication domain. 288.\" ========== 289.It Bq Er EALREADY 290A previous connection attempt has not yet been completed. 291.\" ========== 292.It Bq Er EBADF 293.Fa socket 294is not a valid descriptor. 295.\" ========== 296.It Bq Er ECONNREFUSED 297The attempt to connect was ignored 298(because the target is not listening for connections) 299or explicitly rejected. 300.\" ========== 301.It Bq Er EFAULT 302Part of 303.Fa iov 304or data to be written to 305.Fa socket 306points outside the process's allocated address space. 307.\" ========== 308.It Bq Er EHOSTUNREACH 309The target host cannot be reached (e.g., down, disconnected). 310.\" ========== 311.It Bq Er EINPROGRESS 312The connection cannot be completed immediately. 313It is possible to 314.Xr select 2 315for completion by selecting the 316.Fa socket 317for writing. 318.\" ========== 319.It Bq Er EINTR 320Its execution was interrupted by a signal. 321.\" ========== 322.It Bq Er EMSGSIZE 323The size of the message exceeds the available send buffer space in the 324.Fa socket . 325.\" ========== 326.It Bq Er EINVAL 327An invalid argument was detected 328(e.g., 329.Fa sae_dstaddrlen 330is not valid, the contents of 331.Fa sae_srcaddr 332or 333.Fa sae_dstaddr, 334buffer is invalid, etc.) 335.\" ========== 336.It Bq Er EISCONN 337The socket is already connected. 338.\" ========== 339.It Bq Er ENETDOWN 340The local network interface is not functioning. 341.\" ========== 342.It Bq Er ENETUNREACH 343The network isn't reachable from this host. 344.\" ========== 345.It Bq Er ENOBUFS 346The system call was unable to allocate a needed memory buffer. 347.\" ========== 348.It Bq Er ENOTSOCK 349.Fa socket 350is not a file descriptor for a socket. 351.\" ========== 352.It Bq Er EOPNOTSUPP 353Because 354.Fa socket 355is 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 363Connection 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 383The 384.Fn connectx 385function call appeared in Darwin 15.0.0 386