bsd/man/man2/connectx.2

   1 .\"
   2 .\" Copyright (c) 2012 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. The rights granted to you under the License
  10 .\" may not be used to create, or enable the creation or redistribution of,
  11 .\" unlawful or unlicensed copies of an Apple operating system, or to
  12 .\" circumvent, violate, or enable the circumvention or violation of, any
  13 .\" terms of an Apple operating system software license agreement.
  14 .\"
  15 .\" Please obtain a copy of the License at
  16 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
  17 .\"
  18 .\" The Original Code and all software distributed under the License are
  19 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23 .\" Please see the License for the specific language governing rights and
  24 .\" limitations under the License.
  25 .\"
  26 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27 .\"
  28 .Dd November 14, 2012
  29 .Dt CONNECTX 2
  30 .Os Darwin
  31 .Sh NAME
  32 .Nm connectx
  33 .Nd initiate one or more connections on a socket
  34 .Sh SYNOPSIS
  35 .Fd #include <sys/socket.h>
  36 .Ft int
  37 .Fo connectx
  38 .Fa "int socket"
  39 .Fa "const struct sockaddr *saddress"
  40 .Fa "socklen_t saddress_len"
  41 .Fa "const struct sockaddr *daddress"
  42 .Fa "socklen_t daddress_len"
  43 .Fa "unsigned int ifscope"
  44 .Fa "associd_t associd"
  45 .Fa "connid_t *connid"
  46 .Fc
  47 .Sh DESCRIPTION
  48 The parameter
  49 .Fa socket
  50 is a socket.  The communication domain of the socket determines the
  51 availability and behavior of
  52 .Fn connectx .
  53 In general,
  54 .Fn connectx
  55 may be used as a substitute for cases when
  56 .Xr bind 2
  57 and
  58 .Xr connect 2
  59 are issued in succession.
  60 .Pp
  61 When the source address
  62 .Fa saddress
  63 parameter is specified,
  64 .Fn connectx
  65 binds the connection to one of the addresses, as if
  66 .Xr bind 2
  67 is used.  The length of
  68 .Fa saddress
  69 buffer is specified by
  70 .Fa saddress_len .
  71 This buffer may hold more than one addresses, where each successive address
  72 immediately follows the previous one.  The parameter
  73 .Fa ifscope
  74 may also be specified instead of
  75 .Fa saddress ,
  76 in order to bind the connection to the interface whose interface index
  77 equals to
  78 .Fa ifscope .
  79 Both
  80 .Fa saddress
  81 and
  82 .Fa ifscope
  83 parameters may be specified in order to add more constraints to the connection.
  84 .Pp
  85 At least one destination address must be specified in the
  86 .Fa daddress
  87 parameter.  The
  88 .Fa daddress_len
  89 specifies the length of that buffer.  When more than one addresses
  90 is specified, each successive address immediately follows the previous one.
  91 .Pp
  92 Each communications domain interprets the
  93 .Fa saddress
  94 and
  95 .Fa daddress
  96 parameters in its own way.  When multiple addresses are specified, one
  97 of the addresses will be chosen.  The rules used in selecting the
  98 address vary between communicaton domains.
  99 .Pp
 100 Changes related to the connection state may be monitored by registering for the
 101 .Dv NOTE_CONNINFO_UPDATED
 102 .Xr kqueue 2
 103 event, using the predefined system filter
 104 .Dv EVFILT_SOCK .
 105 Details regarding the event may be retrieved by calling
 106 .Xr getconninfo 3 .
 107 .Sh MULTIPATH
 108 On a multipath socket,
 109 .Fn connectx
 110 may be used multiple times, in order to establish the initial session
 111 association with the peer socket upon the first connection, and to further
 112 establish additional connections related to that assocication on subsequent
 113 ones.
 114 .Pp
 115 The parameter
 116 .Fa associd
 117 specifies the association identifier.  When
 118 .Fn connectx
 119 is initially called to establish an associtation, the association identifier
 120 is not yet known, and
 121 .Dv ASSOCID_ANY
 122 must be specified.  After the initial connection is established, the
 123 association identifier may be retrieved using
 124 .Xr getassocids 3 ,
 125 and the value may then be used on subsequent
 126 .Fn connectx
 127 calls.
 128 .Pp
 129 If the initial connection is established without any protocol-level
 130 multipath association, the error
 131 .Er EPROTO
 132 will be returned, and the connection can be extracted to a new socket with
 133 the same properties of
 134 .Fa socket ,
 135 by calling
 136 .Xr peeloff 2 .
 137 .Pp
 138 An association representing one or more connections, or a single connection
 139 may be dissolved by calling
 140 .Xr disconnectx 2 .
 141 .Sh NON-MULTIPATH
 142 On non-multipath socket,
 143 .Fn connectx
 144 behaves much like a combination of
 145 .Xr bind 2
 146 and
 147 .Xr connect 2 .
 148 The parameter
 149 .Fa associd
 150 must always be set to
 151 .Dv ASSOCID_ANY .
 152 .Pp
 153 Generally, non-multipath stream sockets may successfully
 154 .Fn connectx
 155 only once; datagram sockets may use
 156 .Fn connectx
 157 multiple times to change their association, after first dissolving the
 158 existing association by calling
 159 .Xr disconnectx 2 .
 160 .Sh RETURN VALUES
 161 Upon successful completion, a value of 0 is returned and the connection
 162 identifier is returned through the
 163 .Fa connid
 164 parameter.  If the initial connection establishes an association with
 165 a peer socket, the association identifier may be retrieved by calling
 166 .Xr getassocids 2 .
 167 Both of these identifiers are unique
 168 on a per
 169 .Fa socket
 170 basis.  Upon failure, a value of -1 is returned and the global integer
 171 variable
 172 .Va errno
 173 is set to indicate the error.
 174 .Sh ERRORS
 175 The
 176 .Fn connectx
 177 system call will fail if:
 178 .Bl -tag -width Er
 179 .\" ==========
 180 .It Bq Er EACCES
 181 The destination address is a broadcast address and the
 182 socket option
 183 .Dv SO_BROADCAST
 184 is not set.
 185 .\" ==========
 186 .It Bq Er EADDRINUSE
 187 The address is already in use.
 188 .\" ==========
 189 .It Bq Er EADDRNOTAVAIL
 190 The specified address is not available on this machine.
 191 .\" ==========
 192 .It Bq Er EAFNOSUPPORT
 193 Addresses in the specified address family cannot be used with this socket.
 194 .\" ==========
 195 .It Bq Er EALREADY
 196 The socket is non-blocking
 197 and a previous connection attempt
 198 has not yet been completed.
 199 .\" ==========
 200 .It Bq Er EBADF
 201 .Fa socket
 202 is not a valid descriptor.
 203 .\" ==========
 204 .It Bq Er ECONNREFUSED
 205 The attempt to connect was ignored
 206 (because the target is not listening for connections)
 207 or explicitly rejected.
 208 .\" ==========
 209 .It Bq Er EFAULT
 210 The
 211 .Fa address
 212 parameter specifies an area outside
 213 the process address space.
 214 .\" ==========
 215 .It Bq Er EHOSTUNREACH
 216 The target host cannot be reached (e.g., down, disconnected).
 217 .\" ==========
 218 .It Bq Er EINPROGRESS
 219 The socket is non-blocking
 220 and the connection cannot
 221 be completed immediately.
 222 It is possible to
 223 .Xr select 2
 224 for completion by selecting the socket for writing.
 225 .\" ==========
 226 .It Bq Er EINTR
 227 Its execution was interrupted by a signal.
 228 .\" ==========
 229 .It Bq Er EINVAL
 230 An invalid argument was detected
 231 (e.g.,
 232 .Fa address_len
 233 is not valid for the address family,
 234 the specified address family is invalid).
 235 .\" ==========
 236 .It Bq Er EISCONN
 237 The socket is already connected.
 238 .\" ==========
 239 .It Bq Er ENETDOWN
 240 The local network interface is not functioning.
 241 .\" ==========
 242 .It Bq Er ENETUNREACH
 243 The network isn't reachable from this host.
 244 .\" ==========
 245 .It Bq Er ENOBUFS
 246 The system call was unable to allocate a needed memory buffer.
 247 .\" ==========
 248 .It Bq Er ENOTSOCK
 249 .Fa socket
 250 is not a file descriptor for a socket.
 251 .\" ==========
 252 .It Bq Er EOPNOTSUPP
 253 Because
 254 .Fa socket
 255 is listening, no connection is allowed.
 256 .\" ==========
 257 .It Bq Er EPROTO
 258 The connection was successfully established without any protocol-level
 259 association.  The connection can be extracted to a new socket using
 260 .Xr peeloff 2 .
 261 .\" ==========
 262 .It Bq Er EPROTOTYPE
 263 .Fa address
 264 has a different type than the socket
 265 that is bound to the specified peer address.
 266 .\" ==========
 267 .It Bq Er ETIMEDOUT
 268 Connection establishment timed out without establishing a connection.
 269 .\" ==========
 270 .It Bq Er ECONNRESET
 271 Remote host reset the connection request.
 272 .Sh SEE ALSO
 273 .Xr accept 2 ,
 274 .Xr bind 2 ,
 275 .Xr connect 2 ,
 276 .Xr disconnectx 2 ,
 277 .Xr kqueue 2 ,
 278 .Xr peeloff 2 ,
 279 .Xr select 2 ,
 280 .Xr socket 2 ,
 281 .Xr getassocids 3 ,
 282 .Xr getconnids 3 ,
 283 .Xr getconninfo 3 ,
 284 .Xr compat 5
 285 .Sh HISTORY
 286 The
 287 .Fn connectx
 288 function call appeared in Darwin 13.0.0