connectx(2) BSD System Calls Manual connectx(2)
NAME
connectx -- initiate a connection on a socket
SYNOPSIS
#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);
DESCRIPTION
The parameter socket is a socket. In general, connectx() may be used as
a substitute for cases when bind(2) and connect(2) are issued in succes-
sion, as well as a mechanism to transmit data at connection establishment
time.
The connectx() 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,
connectx() 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
connectx() 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 parame-
ter, 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 indi-
cate to the communication domain that the data is idempotent. For exam-
ple, 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 connectx() 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.
NOTES
connectx() is currently supported only on AF_INET and AF_INET6 sockets of
type SOCK_DGRAM and SOCK_STREAM.
Generally, connection-oriented sockets may successfully connectx() only
once. Connectionless sockets may use connectx() to create an association
to the peer socket, and it may call disconnectx(2) to dissolve any exist-
ing 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, connectx()
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).
RETURN VALUES
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.
ERRORS
The connectx() system call will fail if:
[EADDRINUSE] The address specified in sae_srcaddr parameter is
already in use.
[EADDRNOTAVAIL] The specified in sae_srcaddr parameter is not avail-
able on this machine, or is not assigned to the inter-
face specified by sae_srcif.
[EAFNOSUPPORT] The socket cannot find any usable addresses of a spe-
cific address family as required by the communication
domain.
[EALREADY] A previous connection attempt has not yet been com-
pleted.
[EBADF] socket is not a valid descriptor.
[ECONNREFUSED] The attempt to connect was ignored (because the target
is not listening for connections) or explicitly
rejected.
[EFAULT] Part of iov or data to be written to socket points
outside the process's allocated address space.
[EHOSTUNREACH] The target host cannot be reached (e.g., down, discon-
nected).
[EINPROGRESS] The connection cannot be completed immediately. It is
possible to select(2) for completion by selecting the
socket for writing.
[EINTR] Its execution was interrupted by a signal.
[EMSGSIZE] The size of the message exceeds the available send
buffer space in the socket.
[EINVAL] An invalid argument was detected (e.g., sae_dstaddrlen
is not valid, the contents of sae_srcaddr or
sae_dstaddr, buffer is invalid, etc.)
[EISCONN] The socket is already connected.
[ENETDOWN] The local network interface is not functioning.
[ENETUNREACH] The network isn't reachable from this host.
[ENOBUFS] The system call was unable to allocate a needed memory
buffer.
[ENOTSOCK] socket is not a file descriptor for a socket.
[EOPNOTSUPP] Because socket is listening, no connection is allowed.
[ETIMEDOUT] Connection establishment timed out without establish-
ing a connection.
SEE ALSO
bind(2), connect(2), disconnectx(2), disconnectx(2), getsockopt(2),
select(2), socket(2), writev(2), compat(5)
HISTORY
The connectx() function call appeared in Darwin 15.0.0
Darwin March 26, 2015 Darwin
Mac OS X 10.13.1 - Generated Mon Nov 6 05:55:37 CST 2017