Copyright (c) 2012 Apple Inc. All rights reserved.
@APPLE_OSREFERENCE_LICENSE_HEADER_START@
This file contains Original Code and/or Modifications of Original Code
as defined in and that are subject to the Apple Public Source License
Version 2.0 (the 'License'). You may not use this file except in
compliance with the License. The rights granted to you under the License
may not be used to create, or enable the creation or redistribution of,
unlawful or unlicensed copies of an Apple operating system, or to
circumvent, violate, or enable the circumvention or violation of, any
terms of an Apple operating system software license agreement.
Please obtain a copy of the License at
http://www.opensource.apple.com/apsl/ and read it before using this file.
The Original Code and all software distributed under the License are
distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
Please see the License for the specific language governing rights and
limitations under the License.
@APPLE_OSREFERENCE_LICENSE_HEADER_END@
.Dd November 14, 2012 .Dt CONNECTX 2 .Os Darwin .Sh NAME .Nm connectx .Nd initiate one or more connections on a socket .Sh SYNOPSIS .Fd #include <sys/socket.h> .Ft int .Fo connectx .Fa "int socket" .Fa "const struct sockaddr *saddress" .Fa "socklen_t saddress_len" .Fa "const struct sockaddr *daddress" .Fa "socklen_t daddress_len" .Fa "unsigned int ifscope" .Fa "associd_t associd" .Fa "connid_t *connid" .Fc .Sh DESCRIPTION The parameter .Fa socket is a socket. The communication domain of the socket determines the availability and behavior of .Fn connectx . In general, .Fn connectx may be used as a substitute for cases when .Xr bind 2 and .Xr connect 2 are issued in succession.
p When the source address .Fa saddress parameter is specified, .Fn connectx binds the connection to one of the addresses, as if .Xr bind 2 is used. The length of .Fa saddress buffer is specified by .Fa saddress_len . This buffer may hold more than one addresses, where each successive address immediately follows the previous one. The parameter .Fa ifscope may also be specified instead of .Fa saddress , in order to bind the connection to the interface whose interface index equals to .Fa ifscope . Both .Fa saddress and .Fa ifscope parameters may be specified in order to add more constraints to the connection.
p At least one destination address must be specified in the .Fa daddress parameter. The .Fa daddress_len specifies the length of that buffer. When more than one addresses is specified, each successive address immediately follows the previous one.
p Each communications domain interprets the .Fa saddress and .Fa daddress parameters in its own way. When multiple addresses are specified, one of the addresses will be chosen. The rules used in selecting the address vary between communicaton domains.
p Changes related to the connection state may be monitored by registering for the .Dv NOTE_CONNINFO_UPDATED .Xr kqueue 2 event, using the predefined system filter .Dv EVFILT_SOCK . Details regarding the event may be retrieved by calling .Xr getconninfo 3 . .Sh MULTIPATH On a multipath socket, .Fn connectx may be used multiple times, in order to establish the initial session association with the peer socket upon the first connection, and to further establish additional connections related to that assocication on subsequent ones.
p The parameter .Fa associd specifies the association identifier. When .Fn connectx is initially called to establish an associtation, the association identifier is not yet known, and .Dv ASSOCID_ANY must be specified. After the initial connection is established, the association identifier may be retrieved using .Xr getassocids 3 , and the value may then be used on subsequent .Fn connectx calls.
p If the initial connection is established without any protocol-level multipath association, the error .Er EPROTO will be returned, and the connection can be extracted to a new socket with the same properties of .Fa socket , by calling .Xr peeloff 2 .
p An association representing one or more connections, or a single connection may be dissolved by calling .Xr disconnectx 2 . .Sh NON-MULTIPATH On non-multipath socket, .Fn connectx behaves much like a combination of .Xr bind 2 and .Xr connect 2 . The parameter .Fa associd must always be set to .Dv ASSOCID_ANY .
p
Generally, non-multipath stream sockets may successfully
.Fn connectx
only once; datagram sockets may use
.Fn connectx
multiple times to change their association, after first dissolving the
existing association by calling
.Xr disconnectx 2 .
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned and the connection
identifier is returned through the
.Fa connid
parameter. If the initial connection establishes an association with
a peer socket, the association identifier may be retrieved by calling
.Xr getassocids 2 .
Both of these identifiers are unique
on a per
.Fa socket
basis. Upon failure, a value of -1 is returned and the global integer
variable
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn connectx
system call will fail if:
l -tag -width Er ==========
t Bq Er EACCES The destination address is a broadcast address and the
socket option
.Dv SO_BROADCAST
is not set.
==========
t Bq Er EADDRINUSE The address is already in use.
==========
t Bq Er EADDRNOTAVAIL The specified address is not available on this machine.
==========
t Bq Er EAFNOSUPPORT Addresses in the specified address family cannot be used with this socket.
==========
t Bq Er EALREADY The socket is non-blocking
and a previous connection attempt
has not yet been completed.
==========
t Bq Er EBADF .Fa socket
is not a valid descriptor.
==========
t Bq Er ECONNREFUSED The attempt to connect was ignored
(because the target is not listening for connections)
or explicitly rejected.
==========
t Bq Er EFAULT The
.Fa address
parameter specifies an area outside
the process address space.
==========
t Bq Er EHOSTUNREACH The target host cannot be reached (e.g., down, disconnected).
==========
t Bq Er EINPROGRESS The socket is non-blocking
and the connection cannot
be completed immediately.
It is possible to
.Xr select 2
for completion by selecting the socket for writing.
==========
t Bq Er EINTR Its execution was interrupted by a signal.
==========
t Bq Er EINVAL An invalid argument was detected
(e.g.,
.Fa address_len
is not valid for the address family,
the specified address family is invalid).
==========
t Bq Er EISCONN The socket is already connected.
==========
t Bq Er ENETDOWN The local network interface is not functioning.
==========
t Bq Er ENETUNREACH The network isn't reachable from this host.
==========
t Bq Er ENOBUFS The system call was unable to allocate a needed memory buffer.
==========
t Bq Er ENOTSOCK .Fa socket
is not a file descriptor for a socket.
==========
t Bq Er EOPNOTSUPP Because
.Fa socket
is listening, no connection is allowed.
==========
t Bq Er EPROTO The connection was successfully established without any protocol-level
association. The connection can be extracted to a new socket using
.Xr peeloff 2 .
==========
t Bq Er EPROTOTYPE .Fa address
has a different type than the socket
that is bound to the specified peer address.
==========
t Bq Er ETIMEDOUT Connection establishment timed out without establishing a connection.
==========
t Bq Er ECONNRESET Remote host reset the connection request.
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr disconnectx 2 ,
.Xr kqueue 2 ,
.Xr peeloff 2 ,
.Xr select 2 ,
.Xr socket 2 ,
.Xr getassocids 3 ,
.Xr getconnids 3 ,
.Xr getconninfo 3 ,
.Xr compat 5
.Sh HISTORY
The
.Fn connectx
function call appeared in Darwin 13.0.0