share/man/man3dat/dat_ep_connect.3dat

   1 '\" te
   2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
   3 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DAT_EP_CONNECT 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_ep_connect \- establish a connection between the local Endpoint and a
  10 remote Endpoint
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <\fBdat/udat.h\fR>
  16
  17 DAT_RETURN
  18     dat_ep_connect (
  19     IN    DAT_EP_HANDLE         ep_handle,
  20     IN    DAT_IA_ADDRESS_PTR    remote_ia_address,
  21     IN    DAT_CONN_QUAL         remote_conn_qual,
  22     IN    DAT_TIMEOUT           timeout,
  23     IN    DAT_COUNT             private_data_size,
  24     IN const  DAT_PVOID         private_data,
  25     IN    DAT_QOS               qos,
  26     IN    DAT_CONNECT_FLAGS     connect_flags
  27     )
  28 .fi
  29
  30 .SH PARAMETERS
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIep_handle\fR\fR
  35 .ad
  36 .RS 21n
  37 Handle for an instance of an Endpoint.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIremote_ia_address\fR\fR
  44 .ad
  45 .RS 21n
  46 The Address of the remote IA to which an Endpoint is requesting a connection.
  47 .RE
  48
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIremote_conn_qual\fR\fR
  53 .ad
  54 .RS 21n
  55 Connection Qualifier of the remote IA from which an Endpoint requests a
  56 connection.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fItimeout\fR\fR
  63 .ad
  64 .RS 21n
  65 Duration of time, in microseconds, that a Consumer waits for Connection
  66 establishment. The value of \fBDAT_TIMEOUT_INFINITE\fR represents no timeout,
  67 indefinite wait. Values must be positive.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIprivate_data_size\fR\fR
  74 .ad
  75 .RS 21n
  76 Size of the \fIprivate_data\fR. Must be nonnegative.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fIprivate_data\fR\fR
  83 .ad
  84 .RS 21n
  85 Pointer to the private data that should be provided to the remote Consumer as
  86 part of the Connection Request. If \fIprivate_data_size\fR is zero, then
  87 \fIprivate_data\fR can be \fINULL\fR.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fIqos\fR\fR
  94 .ad
  95 .RS 21n
  96 Requested quality of service of the connection.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fIconnect_flags\fR\fR
 103 .ad
 104 .RS 21n
 105 Flags for the requested connection. If the least significant bit of
 106 \fBDAT_MULTIPATH_FLAG\fR is 0, the Consumer does not request multipathing. If
 107 the least significant bit of \fBDAT__MULTIPATH_FLAG\fR is 1, the Consumer
 108 requests multipathing. The default value is \fBDAT_CONNECT_DEFAULT_FLAG\fR,
 109 which is 0.
 110 .RE
 111
 112 .SH DESCRIPTION
 113 .sp
 114 .LP
 115 The \fBdat_ep_connect()\fR function requests that a connection be established
 116 between the local Endpoint and a remote Endpoint. This operation is used by the
 117 active/client side Consumer of the Connection establishment model. The remote
 118 Endpoint is identified by Remote IA and Remote Connection Qualifier.
 119 .sp
 120 .LP
 121 As part of the successful completion of this operation, the local Endpoint is
 122 bound to a Port Qualifier of the local IA. The Port Qualifier is passed to the
 123 remote side of the requested connection and is available to the remote Consumer
 124 in the Connection Request of the \fBDAT_CONNECTION_REQUEST_EVENT\fR.
 125 .sp
 126 .LP
 127 The Consumer-provided \fIprivate_data\fR is passed to the remote side and is
 128 provided to the remote Consumer in the Connection Request. Consumers can
 129 encapsulate any local Endpoint attributes that remote Consumers need to know as
 130 part of an upper-level protocol. Providers can also provide a Provider on the
 131 remote side any local Endpoint attributes and Transport-specific information
 132 needed for Connection establishment by the Transport.
 133 .sp
 134 .LP
 135 Upon successful completion of this operation, the local Endpoint is transferred
 136 into \fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR.
 137 .sp
 138 .LP
 139 Consumers can request a specific value of \fIqos\fR. The Provider specifies
 140 which quality of service it supports in documentation and in the Provider
 141 attributes. If the local Provider or Transport does not support the requested
 142 \fIqos\fR, the operation fails and \fBDAT_MODEL_NOT_SUPPORTED\fR is returned
 143 synchronously. If the remote Provider does not support the requested \fIqos\fR,
 144 the local Endpoint is automatically transitioned into the
 145 \fBDAT_EP_STATE_DISCONNECTED\fR state, the connection is not established, and
 146 the event returned on the \fIconnect_evd_handle\fR is
 147 \fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR. The same
 148 \fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR event is returned if the
 149 connection cannot be established for all reasons of not establishing the
 150 connection, except timeout, remote host not reachable, and remote peer reject.
 151 For example, remote Consumer is not listening on the requested Connection
 152 Qualifier, Backlog of the requested Service Point is full, and Transport
 153 errors. In this case, the local Endpoint is automatically transitioned into
 154 \fBDAT_EP_STATE_DISCONNECTED\fR state.
 155 .sp
 156 .LP
 157 The acceptance of the requested connection by the remote Consumer is reported
 158 to the local Consumer through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on
 159 the \fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is
 160 automatically transitioned into a \fBDAT_EP_STATE_CONNECTED\fR state.
 161 .sp
 162 .LP
 163 The rejection of the connection by the remote Consumer is reported to the local
 164 Consumer through a \fBDAT_CONNECTION_EVENT_PEER_REJECTED\fR event on the
 165 \fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is
 166 automatically transitioned into a \fBDAT_EP_STATE_DISCONNECTED\fR state.
 167 .sp
 168 .LP
 169 When the Provider cannot reach the remote host or the remote host does not
 170 respond within the Consumer requested Timeout, a
 171 \fBDAT_CONNECTION_EVENT_UNREACHABLE\fR event is generated on the
 172 \fIconnect_evd_handle\fR of the Endpoint. The Endpoint transitions into a
 173 \fBDAT_EP_STATE_DISCONNECTED\fR state.
 174 .sp
 175 .LP
 176 If the Provider can locally determine that the \fIremote_ia_address\fR is
 177 invalid, or that the remote_ia_address cannot be converted to a
 178 Transport-specific address, the operation can fail synchronously with a
 179 \fBDAT_INVALID_ADDRESS\fR return.
 180 .sp
 181 .LP
 182 The local Endpoint is automatically transitioned into a
 183 \fBDAT_EP_STATE_CONNECTED\fR state when a Connection Request accepted by the
 184 remote Consumer and the Provider completes the Transport-specific Connection
 185 establishment. The local Consumer is notified of the established connection
 186 through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on the
 187 \fIconnect_evd_handle\fR of the local Endpoint.
 188 .sp
 189 .LP
 190 When the \fItimeout\fR expired prior to completion of the Connection
 191 establishment, the local Endpoint is automatically transitioned into a
 192 \fBDAT_EP_STATE_DISCONNECTED\fR state and the local Consumer through a
 193 \fBDAT_CONNECTION_EVENT_TIMED_OUT\fR event on the \fIconnect_evd_handle\fR of
 194 the local Endpoint.
 195 .SH RETURN VALUES
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBDAT_SUCCESS\fR\fR
 200 .ad
 201 .RS 30n
 202 The operation was successful.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
 209 .ad
 210 .RS 30n
 211 The operation failed due to resource limitations.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 218 .ad
 219 .RS 30n
 220 Invalid parameter.
 221 .RE
 222
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBDAT_INVALID_ADDRESS\fR\fR
 227 .ad
 228 .RS 30n
 229 Invalid address.
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBDAT_INVALID_HANDLE\fR\fR
 236 .ad
 237 .RS 30n
 238 Invalid DAT handle; Invalid Endpoint handle.
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fBDAT_INVALID_STATE\fR\fR
 245 .ad
 246 .RS 30n
 247 Parameter in an invalid state. Endpoint was not in
 248 \fBDAT_EP_STATE_UNCONNECTED\fR state.
 249 .RE
 250
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
 255 .ad
 256 .RS 30n
 257 The requested Model was not supported by the Provider. For example, the
 258 requested qos was not supported by the local Provider.
 259 .RE
 260
 261 .SH USAGE
 262 .sp
 263 .LP
 264 It is up to the Consumer to negotiate outstanding RDMA Read incoming and
 265 outgoing with a remote peer. The outstanding RDMA Read outgoing attribute
 266 should be smaller than the remote Endpoint outstanding RDMA Read incoming
 267 attribute. If this is not the case, Connection establishment might fail.
 268 .sp
 269 .LP
 270 DAT API does not define a protocol on how remote peers exchange Endpoint
 271 attributes. The exchange of outstanding RDMA Read incoming and outgoing
 272 attributes of EPs is left to the Consumer ULP. The Consumer can use Private
 273 Data for it.
 274 .sp
 275 .LP
 276 If the Consumer does not care about posting RDMA Read operations or remote RDMA
 277 Read operations on the connection, it can set the two outstanding RDMA Read
 278 attribute values to 0.
 279 .sp
 280 .LP
 281 If the Consumer does not set the two outstanding RDMA Read attributes of the
 282 Endpoint, the Provider is free to pick up any value for default. The Provider
 283 is allowed to change these default values during connection setup.
 284 .SH ATTRIBUTES
 285 .sp
 286 .LP
 287 See \fBattributes\fR(5) for descriptions of the following attributes:
 288 .sp
 289
 290 .sp
 291 .TS
 292 box;
 293 c | c
 294 l | l .
 295 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 296 _
 297 Interface Stability     Standard: uDAPL, 1.1, 1.2
 298 _
 299 MT-Level        Unsafe
 300 .TE
 301
 302 .SH SEE ALSO
 303 .sp
 304 .LP
 305 \fBlibdat\fR(3LIB), \fBattributes\fR(5)