CONNECTX(2) System Calls Manual CONNECTX(2)

connectx — initiate a connection on a socket

#include <sys/socket.h>

int
connectx(int socket, const sa_endpoints_t *endpoints, sae_associd_t associd, unsigned int flags, const struct iovec *iov, unsigned int iovcnt, size_t *len, sae_connid_t *connid);

The parameter socket is a socket. In general, () may be used as a substitute for cases when bind(2) and connect(2) are issued in succession, as well as a mechanism to transmit data at connection establishment time.

The () system call uses a sa_endpoints structure to minimize the number of directly supplied arguments. This structure has the following form, as defined in <sys/socket.h>:

typedef struct sa_endpoints {
	unsigned int     sae_srcif;      /* optional source interface   */
	struct sockaddr *sae_srcaddr;    /* optional source address     */
	socklen_t        sae_srcaddrlen; /* size of source address      */
	struct sockaddr *sae_dstaddr;    /* destination address         */
	socklen_t        sae_dstaddrlen; /* size of destination address */
}sa_endpoints_t;

When the optional source address sae_srcaddr parameter is specified, () binds the connection to the address, as if bind(2) is used. The length of sae_srcaddr buffer is specified by sae_srcaddrlen. The source address can be obtained by calling getifaddrs(3).

The optional parameter sae_srcif may also be specified, in order to force the connection to use the interface whose interface index equals to sae_srcif. The value for sae_srcif may be obtained by issuing a call to if_nametoindex(3). If only sae_srcif is specified, the communication domain will choose a source address on that interface for communicating to the peer socket. Both sae_srcaddr and sae_srcif parameters may also be specified in order to add more constraints to the connection, and () will fail unless the address is currently assigned to that interface.

A destination address must be specified in the sae_dstaddr parameter. The sae_dstaddrlen specifies the length of that buffer.

Data to be transmitted may optionally be defined via the iovcnt buffers specified by members of the iov array, along with a non-NULL len parameter, which upon success, indicates the number of bytes enqueued for transmission.

When the iov and len parameters are non-NULL, the communication domain will copy the data to the socket send buffer. The communication domain may impose a limit on the amount of data allowed to be buffered before connection establishment.

When the flags parameter is set to CONNECT_RESUME_ON_READ_WRITE and an iov is not passed in, the communication domain will trigger the actual connection establishment upon the first read or write following the connectx(2) system call. This flag is ignored if the iov is specified in the connectx(2) call itself.

The flags parameter may also be set to CONNECT_DATA_IDEMPOTENT to indicate to the communication domain that the data is idempotent. For example, this will trigger TCP Fast Open (RFC 7413) with SOCK_STREAM type. The data must be passed in the iov parameter in connectx(2) , or passed in with the first write call such as with the writev(2) or similar system call if the CONNECT_RESUME_ON_READ_WRITE is also set.

In general, the communication domain makes the final decision on the amount of data that may get transmitted at connection establishment time. If the socket requires the data be sent atomically and the data size makes this impossible, EMSGSIZE will be returned and the state of the socket is left unchanged as if () was not called.

The parameter associd is reserved for future use, and must always be set to SAE_ASSOCID_ANY. The parameter connid is also reserved for future use and should be set to NULL.

() is currently supported only on AF_INET and AF_INET6 sockets of type SOCK_DGRAM and SOCK_STREAM.

Generally, connection-oriented sockets may successfully () only once. Connectionless sockets may use connectx() to create an association to the peer socket, and it may call disconnectx(2) to dissolve any existing association. Unlike connection-oriented sockets, connectionless sockets may call connectx() again afterwards to associate to another peer socket.

If CONNECT_RESUME_ON_READ_WRITE is set without data supplied, () will immediately return success, assuming the rest of the parameters are valid. select(2) will indicate that the socket is ready for writing, and the actual connection establishment is attempted once the initial data is written to the socket via writev(2) or similar. Subsequent attempts to write more data will fail until the existing connection establishment attempt is successful. The error status of the socket may be retrieved via the SO_ERROR option using getsockopt(2).

Upon successful completion, a value of 0 is returned. The number of bytes from iov array which were enqueued for transmission is returned via len. Upon failure, a value of -1 is returned and the global integer variable errno is set to indicate the error.

The connectx() system call will fail if:

[]
The address specified in sae_srcaddr parameter is already in use.
[]
The specified in sae_srcaddr parameter is not available on this machine, or is not assigned to the interface specified by sae_srcif.
[]
The socket cannot find any usable addresses of a specific address family as required by the communication domain.
[]
A previous connection attempt has not yet been completed.
[]
socket is not a valid descriptor.
[]
The attempt to connect was ignored (because the target is not listening for connections) or explicitly rejected.
[]
Part of iov or data to be written to socket points outside the process's allocated address space.
[]
The target host cannot be reached (e.g., down, disconnected).
[]
The connection cannot be completed immediately. It is possible to select(2) for completion by selecting the socket for writing.
[]
Its execution was interrupted by a signal.
[]
The size of the message exceeds the available send buffer space in the socket.
[]
An invalid argument was detected (e.g., sae_dstaddrlen is not valid, the contents of sae_srcaddr or sae_dstaddr, buffer is invalid, etc.)
[]
The socket is already connected.
[]
The local network interface is not functioning.
[]
The network isn't reachable from this host.
[]
The system call was unable to allocate a needed memory buffer.
[]
socket is not a file descriptor for a socket.
[]
Because socket is listening, no connection is allowed.
[]
Connection establishment timed out without establishing a connection.

bind(2), connect(2), disconnectx(2), disconnectx(2), getsockopt(2), select(2), socket(2), writev(2), compat(5)

The connectx() function call appeared in Darwin 15.0.0

March 26, 2015 Darwin