]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/connectx.2
xnu-7195.101.1.tar.gz
[apple/xnu.git] / 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