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