2 .\" Copyright (c) 2015 Apple Inc. All rights reserved.
4 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
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.
15 .\" Please obtain a copy of the License at
16 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
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.
26 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
33 .Nd initiate a connection on a socket
35 .Fd #include <sys/socket.h>
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"
45 .Fa "sae_connid_t *connid"
53 may be used as a substitute for cases when
57 are issued in succession, as well as a mechanism to transmit data
58 at connection establishment time.
64 structure to minimize the number of directly supplied arguments. This structure
65 has the following form, as defined in
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 */
78 When the optional source address
80 parameter is specified,
82 binds the connection to the address, as if
84 is used. The length of
86 buffer is specified by
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
93 The optional parameter
95 may also be specified, in order to force the connection to use the interface
96 whose interface index equals to
100 may be obtained by issuing a call to
101 .Xr if_nametoindex 3 .
104 is specified, the communication domain will choose a source address on that
105 interface for communicating to the peer socket. Both
109 parameters may also be specified in order to add more constraints to the connection, and
111 will fail unless the address is currently assigned to that interface.
113 A destination address must be specified in the
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
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.
128 .\" Changes related to the connection state may be monitored by registering for the
129 .\" .Dv NOTE_CONNINFO_UPDATED
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 .
136 .\" On a multipath socket,
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
145 .\" specifies the association identifier. When
147 .\" is initially called to establish an associtation, the association identifier
148 .\" is not yet known, and
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
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,
163 .\" behaves much like a combination of
168 Data to be transmitted may optionally be defined via the
170 buffers specified by members of the
172 array, along with a non-NULL
174 parameter, which upon success, indicates the number of bytes enqueued for
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.
184 When the flags parameter is set to CONNECT_RESUME_ON_READ_WRITE and an
186 is not passed in, the communication domain will trigger the actual connection
187 establishment upon the first read or write following the
189 system call. This flag is ignored if the iov is specified in the
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
199 , or passed in with the first write call such as with the
201 or similar system call if the CONNECT_RESUME_ON_READ_WRITE is also set.
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
212 is reserved for future use, and must always be set to
213 .Dv SAE_ASSOCID_ANY .
216 is also reserved for future use and should be set to NULL.
219 is currently supported only on AF_INET and AF_INET6 sockets of type SOCK_DGRAM
224 connection-oriented sockets may successfully
226 only once. Connectionless sockets may use
228 to create an association to the peer socket, and it may call
230 to dissolve any existing association. Unlike connection-oriented sockets,
231 connectionless sockets may call
233 again afterwards to associate to another peer socket.
235 If CONNECT_RESUME_ON_READ_WRITE is set without data
238 will immediately return success, assuming the rest of the parameters are valid.
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
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
248 Upon successful completion, a value of 0 is returned.
249 .\" and an opaque value may be returned through the
252 The number of bytes from
254 array which were enqueued for transmission is returned via
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
262 Upon failure, a value of -1 is returned and the global integer
265 is set to indicate the error.
269 system call will fail if:
273 The address specified in
275 parameter is already in use.
277 .It Bq Er EADDRNOTAVAIL
280 parameter is not available on this machine, or is not assigned to the interface specified by
283 .It Bq Er EAFNOSUPPORT
286 cannot find any usable addresses of a specific address family
287 as required by the communication domain.
290 A previous connection attempt has not yet been completed.
294 is not a valid descriptor.
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.
304 or data to be written to
306 points outside the process's allocated address space.
308 .It Bq Er EHOSTUNREACH
309 The target host cannot be reached (e.g., down, disconnected).
311 .It Bq Er EINPROGRESS
312 The connection cannot be completed immediately.
315 for completion by selecting the
320 Its execution was interrupted by a signal.
323 The size of the message exceeds the available send buffer space in the
327 An invalid argument was detected
330 is not valid, the contents of
334 buffer is invalid, etc.)
337 The socket is already connected.
340 The local network interface is not functioning.
342 .It Bq Er ENETUNREACH
343 The network isn't reachable from this host.
346 The system call was unable to allocate a needed memory buffer.
350 is not a file descriptor for a socket.
355 is listening, no connection is allowed.
357 .\".It Bq Er EPROTOTYPE
359 .\"has a different type than the socket
360 .\"that is bound to the specified peer address.
363 Connection establishment timed out without establishing a connection.
377 .\".Xr getassocids 3 ,
378 .\".Xr getconnids 3 ,
379 .\".Xr getconninfo 3 ,
385 function call appeared in Darwin 15.0.0