.\"
-.\" Copyright (c) 2012 Apple Inc. All rights reserved.
+.\" Copyright (c) 2015 Apple Inc. All rights reserved.
.\"
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
.\"
.\"
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
.\"
-.Dd November 14, 2012
+.Dd March 26, 2015
.Dt CONNECTX 2
.Os Darwin
.Sh NAME
.Nm connectx
-.Nd initiate one or more connections on a socket
+.Nd initiate a connection 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"
+.Fa "const sa_endpoints_t *endpoints"
+.Fa "sae_associd_t associd"
+.Fa "unsigned int flags"
+.Fa "const struct iovec *iov"
+.Fa "unsigned int iovcnt"
+.Fa "size_t *len"
+.Fa "sae_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 .
+is a socket.
In general,
.Fn connectx
may be used as a substitute for cases when
.Xr bind 2
and
.Xr connect 2
-are issued in succession.
+are issued in succession, as well as a mechanism to transmit data
+at connection establishment time.
.Pp
-When the source address
-.Fa saddress
+The
+.Fn connectx
+system call uses a
+.Fa sa_endpoints
+structure to minimize the number of directly supplied arguments. This structure
+has the following form, as defined in
+.In sys/socket.h :
+.Pp
+.Bd -literal
+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;
+.Ed
+.Pp
+When the optional source address
+.Fa sae_srcaddr
parameter is specified,
.Fn connectx
-binds the connection to one of the addresses, as if
+binds the connection to the address, as if
.Xr bind 2
is used. The length of
-.Fa saddress
+.Fa sae_srcaddr
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
+.Fa sae_srcaddrlen .
+.\" This buffer may hold more than one addresses, where each successive address
+.\" immediately follows the previous one.
+The source address can be obtained by calling
+.Xr getifaddrs 3 .
+.Pp
+The optional parameter
+.Fa sae_srcif
+may also be specified, in order to force the connection to use the interface
+whose interface index equals to
+.Fa sae_srcif .
+The value for
+.Fa sae_srcif
+may be obtained by issuing a call to
+.Xr if_nametoindex 3 .
+If only
+.Fa sae_srcif
+is specified, the communication domain will choose a source address on that
+interface for communicating to the peer socket. Both
+.Fa sae_srcaddr
and
-.Fa ifscope
-parameters may be specified in order to add more constraints to the connection.
+.Fa sae_srcif
+parameters may also be specified in order to add more constraints to the connection, and
+.Fn connectx
+will fail unless the address is currently assigned to that interface.
.Pp
-At least one destination address must be specified in the
-.Fa daddress
+A destination address must be specified in the
+.Fa sae_dstaddr
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.
+.Fa sae_dstaddrlen
+specifies the length of that buffer.
+.\" When more than one addresses
+.\" is specified, each successive address immediately follows the previous one.
+.\" Each communication domain interprets the
+.\" .Fa sae_srcaddr
+.\" and
+.\" .Fa sae_dstaddr
+.\" parameters in its own way.
+.\" When multiple addresses are specified, one of the addresses will be chosen.
+.\" The rules used in selecting the eligible addresses as well as their address family requirements vary between communication domains.
+.\" .Pp
+.\" 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 association on subsequent
+.\" ones.
+.\" .Pp
+.\" 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.
+.\" .Pp
+.\" 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 .
+.\" .Pp
+.\" 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 .
.Pp
-Each communications domain interprets the
-.Fa saddress
+Data to be transmitted may optionally be defined via the
+.Fa iovcnt
+buffers specified by members of the
+.Fa iov
+array, along with a non-NULL
+.Fa len
+parameter, which upon success, indicates the number of bytes enqueued for
+transmission.
+.Pp
+When the
+.Fa iov
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.
+.Fa 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.
+.Pp
+When the flags parameter is set to CONNECT_RESUME_ON_READ_WRITE and an
+.Fa iov
+is not passed in, the communication domain will trigger the actual connection
+establishment upon the first read or write following the
+.Xr connectx 2
+system call. This flag is ignored if the iov is specified in the
+.Xr connectx 2
+call itself.
.Pp
-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,
+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
+.Fa iov
+parameter in
+.Xr connectx 2
+, or passed in with the first write call such as with the
+.Xr writev 2
+or similar system call if the CONNECT_RESUME_ON_READ_WRITE is also set.
+.Pp
+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
.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.
+was not called.
.Pp
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
+is reserved for future use, and must always be set to
+.Dv SAE_ASSOCID_ANY .
+The parameter
+.Fa connid
+is also reserved for future use and should be set to NULL.
+.Sh NOTES
.Fn connectx
-calls.
+is currently supported only on AF_INET and AF_INET6 sockets of type SOCK_DGRAM
+and SOCK_STREAM.
.Pp
-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 .
-.Pp
-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,
+Generally,
+.\" non-multipath
+connection-oriented sockets may successfully
.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 .
-.Pp
-Generally, non-multipath stream sockets may successfully
+only once. Connectionless sockets may use
.Fn connectx
-only once; datagram sockets may use
+to create an association to the peer socket, and it may call
+.Xr disconnectx 2
+to dissolve any existing association. Unlike connection-oriented sockets,
+connectionless sockets may call
+.Fn connectx
+again afterwards to associate to another peer socket.
+.Pp
+If CONNECT_RESUME_ON_READ_WRITE is set without data
+supplied,
.Fn connectx
-multiple times to change their association, after first dissolving the
-existing association by calling
-.Xr disconnectx 2 .
+will immediately return success, assuming the rest of the parameters are valid.
+.Xr 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
+.Xr 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
+.Xr getsockopt 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
+Upon successful completion, a value of 0 is returned.
+.\" and an opaque value may be returned through the
+.\" .Fa connid
+.\" parameter.
+The number of bytes from
+.Fa iov
+array which were enqueued for transmission is returned via
+.Fa len .
+.\" 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.
system call will fail if:
.Bl -tag -width Er
.\" ==========
-.It Bq Er EACCES
-The destination address is a broadcast address and the
-socket option
-.Dv SO_BROADCAST
-is not set.
-.\" ==========
.It Bq Er EADDRINUSE
-The address is already in use.
+The address specified in
+.Fa sae_srcaddr
+parameter is already in use.
.\" ==========
.It Bq Er EADDRNOTAVAIL
-The specified address is not available on this machine.
+The specified in
+.Fa sae_srcaddr
+parameter is not available on this machine, or is not assigned to the interface specified by
+.Fa sae_srcif .
.\" ==========
.It Bq Er EAFNOSUPPORT
-Addresses in the specified address family cannot be used with this socket.
+The
+.Fa socket
+cannot find any usable addresses of a specific address family
+as required by the communication domain.
.\" ==========
.It Bq Er EALREADY
-The socket is non-blocking
-and a previous connection attempt
-has not yet been completed.
+A previous connection attempt has not yet been completed.
.\" ==========
.It Bq Er EBADF
.Fa socket
or explicitly rejected.
.\" ==========
.It Bq Er EFAULT
-The
-.Fa address
-parameter specifies an area outside
-the process address space.
+Part of
+.Fa iov
+or data to be written to
+.Fa socket
+points outside the process's allocated address space.
.\" ==========
.It Bq Er EHOSTUNREACH
The target host cannot be reached (e.g., down, disconnected).
.\" ==========
.It Bq Er EINPROGRESS
-The socket is non-blocking
-and the connection cannot
-be completed immediately.
+The connection cannot be completed immediately.
It is possible to
.Xr select 2
-for completion by selecting the socket for writing.
+for completion by selecting the
+.Fa socket
+for writing.
.\" ==========
.It Bq Er EINTR
Its execution was interrupted by a signal.
.\" ==========
+.It Bq Er EMSGSIZE
+The size of the message exceeds the available send buffer space in the
+.Fa socket .
+.\" ==========
.It 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).
+.Fa sae_dstaddrlen
+is not valid, the contents of
+.Fa sae_srcaddr
+or
+.Fa sae_dstaddr,
+buffer is invalid, etc.)
.\" ==========
.It Bq Er EISCONN
The socket is already connected.
.Fa socket
is listening, no connection is allowed.
.\" ==========
-.It 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 .
+.\".It 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 .
.\" ==========
-.It Bq Er EPROTOTYPE
-.Fa address
-has a different type than the socket
-that is bound to the specified peer address.
+.\".It Bq Er EPROTOTYPE
+.\".Fa address
+.\"has a different type than the socket
+.\"that is bound to the specified peer address.
.\" ==========
.It Bq Er ETIMEDOUT
Connection establishment timed out without establishing a connection.
.\" ==========
-.It Bq Er ECONNRESET
-Remote host reset the connection request.
+.El
.Sh SEE ALSO
-.Xr accept 2 ,
+.\".Xr accept 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr disconnectx 2 ,
-.Xr kqueue 2 ,
-.Xr peeloff 2 ,
+.Xr disconnectx 2 ,
+.Xr getsockopt 2 ,
+.\".Xr kqueue 2 ,
+.\".Xr peeloff 2 ,
+.\".Xr shutdown 2 ,
.Xr select 2 ,
.Xr socket 2 ,
-.Xr getassocids 3 ,
-.Xr getconnids 3 ,
-.Xr getconninfo 3 ,
+.\".Xr getassocids 3 ,
+.\".Xr getconnids 3 ,
+.\".Xr getconninfo 3 ,
+.Xr writev 2 ,
.Xr compat 5
.Sh HISTORY
The
.Fn connectx
-function call appeared in Darwin 13.0.0
+function call appeared in Darwin 15.0.0
projects / apple / xnu.git / blobdiff