usr/src/man/man3dat/dat_cr_accept.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_CR_ACCEPT 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_cr_accept \- establishes a Connection between the active remote side
  10 requesting Endpoint and the passive side local 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_cr_accept (
  19     IN    DAT_CR_HANDLE    cr_handle,
  20     IN    DAT_EP_HANDLE    ep_handle,
  21     IN    DAT_COUNT        private_data_size,
  22     IN const DAT_PVOID     private_data
  23     )
  24 .fi
  25
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIcr_handle\fR\fR
  31 .ad
  32 .RS 21n
  33 Handle to an instance of a Connection Request that the Consumer is accepting.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIep_handle\fR\fR
  40 .ad
  41 .RS 21n
  42 Handle for an instance of a local Endpoint that the Consumer is accepting the
  43 Connection Request on. If the local Endpoint is specified by the Connection
  44 Request, the \fIep_handle\fR shall be \fBDAT_HANDLE_NULL\fR.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIprivate_data_size\fR\fR
  51 .ad
  52 .RS 21n
  53 Size of the \fIprivate_data\fR, which must be nonnegative.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIprivate_data\fR\fR
  60 .ad
  61 .RS 21n
  62 Pointer to the private data that should be provided to the remote Consumer when
  63 the Connection is established. If \fIprivate_data_size\fR is zero, then
  64 \fIprivate_data\fR can be \fINULL\fR.
  65 .RE
  66
  67 .SH DESCRIPTION
  68 .sp
  69 .LP
  70 The \fBdat_cr_accept()\fR function establishes a Connection between the active
  71 remote side requesting Endpoint and the passive side local Endpoint. The local
  72 Endpoint is either specified explicitly by \fIep_handle\fR or implicitly by a
  73 Connection Request. In the second case, \fIep_handle\fR is
  74 \fBDAT_HANDLE_NULL\fR.
  75 .sp
  76 .LP
  77 Consumers can specify private data that is provided to the remote side upon
  78 Connection establishment.
  79 .sp
  80 .LP
  81 If the provided local Endpoint does not satisfy the requested Connection
  82 Request, the operation fails without any effect on the local Endpoint, Pending
  83 Connection Request, private data, or remote Endpoint.
  84 .sp
  85 .LP
  86 The operation is asynchronous. The successful completion of the operation is
  87 reported through a Connection Event of type
  88 \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR on the \fIconnect_evd\fR of the local
  89 Endpoint.
  90 .sp
  91 .LP
  92 If the Provider cannot complete the Connection establishment, the connection is
  93 not established and the Consumer is notified through a Connection Event of type
  94 \fBDAT_CONNECTION_EVENT_ACCEPT_COMPLETION_ERROR\fR on the \fIconnect_evd\fR of
  95 the local Endpoint. It can be caused by the active side timeout expiration,
  96 transport error, or any other reason. If Connection is not established,
  97 Endpoint transitions into Disconnected state and all posted Recv DTOs are
  98 flushed to its \fIrecv_evd_handle\fR.
  99 .sp
 100 .LP
 101 This operation, if successful, also destroys the Connection Request instance.
 102 Use of the handle of the destroyed \fIcr_handle\fR in any consequent operation
 103 fails.
 104 .SH RETURN VALUES
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBDAT_SUCCESS\fR\fR
 109 .ad
 110 .RS 25n
 111 The operation was successful.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBDAT_INVALID_HANDLE\fR\fR
 118 .ad
 119 .RS 25n
 120 The \fIcr_handle\fR or \fIep_handle\fR parameter is invalid.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 127 .ad
 128 .RS 25n
 129 The \fIprivate_data_size\fR or \fIprivate_data\fR parameter is invalid, out of
 130 range, or a combination of parameters was invalid
 131 .RE
 132
 133 .SH USAGE
 134 .sp
 135 .LP
 136 Consumers should be aware that Connection establishment might fail in the
 137 following cases: If the accepting Endpoint has an outstanding RDMA Read
 138 outgoing attribute larger than the requesting remote Endpoint or outstanding
 139 RDMA Read incoming attribute, or if the outstanding RDMA Read incoming
 140 attribute is smaller than the requesting remote Endpoint or outstanding RDMA
 141 Read outgoing attribute.
 142 .sp
 143 .LP
 144 Consumers should set the accepting Endpoint RDMA Reads as the target (incoming)
 145 to a number larger than or equal to the remote Endpoint RDMA Read outstanding
 146 as the originator (outgoing), and the accepting Endpoint RDMA Reads as the
 147 originator to a number smaller than or equal to the remote Endpoint RDMA Read
 148 outstanding as the target. DAT API does not define a protocol on how remote
 149 peers exchange Endpoint attributes. The exchange of outstanding RDMA Read
 150 incoming and outgoing attributes of EPs is left to the Consumer ULP. Consumer
 151 can use Private Data for it.
 152 .sp
 153 .LP
 154 If the Consumer does not care about posting RDMA Read operations or remote RDMA
 155 Read operations on the connection, it can set the two outstanding RDMA Read
 156 attribute values to 0.
 157 .sp
 158 .LP
 159 If the Consumer does not set the two outstanding RDMA Read attributes of the
 160 Endpoint, the Provider is free to pick up any value for default. The Provider
 161 can change these default values during connection setup.
 162 .SH ATTRIBUTES
 163 .sp
 164 .LP
 165 See \fBattributes\fR(5) for descriptions of the following attributes:
 166 .sp
 167
 168 .sp
 169 .TS
 170 box;
 171 c | c
 172 l | l .
 173 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 174 _
 175 Interface Stability     Standard: uDAPL, 1.1, 1.2
 176 _
 177 MT-Level        Unsafe
 178 .TE
 179
 180 .SH SEE ALSO
 181 .sp
 182 .LP
 183 \fBlibdat\fR(3LIB), \fBattributes\fR(5)