X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/39236c6e673c41db228275375ab7fdb0f837b292..eee3565979933af707c711411001ba11fe406a3c:/bsd/man/man2/connectx.2

diff --git a/bsd/man/man2/connectx.2 b/bsd/man/man2/connectx.2
index 96e85c7ab..7fbca576e 100644
--- a/bsd/man/man2/connectx.2
+++ b/bsd/man/man2/connectx.2
@@ -1,5 +1,5 @@
 .\" 
-.\" Copyright (c) 2012 Apple Inc. All rights reserved.
+.\" Copyright (c) 2015 Apple Inc. All rights reserved.
 .\" 
 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 .\" 
@@ -25,149 +25,250 @@
 .\" 
 .\" @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.
@@ -177,25 +278,25 @@ The
 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
@@ -207,31 +308,39 @@ The attempt to connect was ignored
 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.
@@ -254,35 +363,38 @@ Because
 .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