usr/src/man/man3dat/dat_ia_open.3dat

   1 '\" te
   2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
   3 .\" Portions Copyright (c) 2009, 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_IA_OPEN 3DAT "Jan 28, 2009"
   8 .SH NAME
   9 dat_ia_open \- open an Interface Adapter (IA)
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <\fBdat/udat.h\fR>
  15
  16 DAT_RETURN
  17     dat_ia_open (
  18     IN const DAT_NAME_PTR       \fIia_name_ptr\fR,
  19     IN       DAT_COUNT          \fIasync_evd_min_qlen\fR,
  20     INOUT    DAT_EVD_HANDLE     *\fIasync_evd_handle\fR,
  21     OUT      DAT_IA_HANDLE      *\fIia_handle\fR
  22     )
  23 .fi
  24
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIia_name_ptr\fR\fR
  30 .ad
  31 .RS 22n
  32 Symbolic name for the IA to be opened. The name should be defined by the
  33 Provider registration.
  34 .sp
  35 If the name is prefixed by the string \fBRO_AWARE_\fR, then the prefix is
  36 removed prior to being passed down and the existence of the prefix indicates
  37 that the application has been coded to correctly deal with relaxed ordering
  38 constraints. If the prefix is not present and the platform on which the
  39 application is running is utilizing relaxed ordering, the open will fail with
  40 \fBDAT_INVALID_PARAMETER\fR (with \fBDAT_SUBTYPE_STATUS\fR of
  41 \fBDAT_INVALID_RO_COOKIE\fR). This setting also affects
  42 \fBdat_lmr_create\fR(3DAT).
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIasync_evd_min_qlen\fR\fR
  49 .ad
  50 .RS 22n
  51 Minimum length of the Asynchronous Event Dispatcher queue.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIasync_evd_handle\fR\fR
  58 .ad
  59 .RS 22n
  60 Pointer to a handle for an Event Dispatcher for asynchronous events generated
  61 by the IA. This parameter can be \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that
  62 there is already EVD for asynchronous events for this Interface Adapter or
  63 \fBDAT_HANDLE_NULL\fR for a Provider to generate EVD for it.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIia_handle\fR\fR
  70 .ad
  71 .RS 22n
  72 Handle for an open instance of a DAT IA. This handle is used with other
  73 functions to specify a particular instance of the IA.
  74 .RE
  75
  76 .SH DESCRIPTION
  77 .sp
  78 .LP
  79 The \fBdat_ia_open()\fR function opens an IA by creating an IA instance.
  80 Multiple instances (opens) of an IA can exist.
  81 .sp
  82 .LP
  83 The value of \fBDAT_HANDLE_NULL\fR for \fIasync_evd_handle\fR
  84 (*\fIasync_evd_handle\fR == \fBDAT_HANDLE_NULL\fR) indicates that the default
  85 Event Dispatcher is created with the requested \fIasync_evd_min_qlen\fR. The
  86 \fIasync_evd_handle\fR returns the handle of the created Asynchronous Event
  87 Dispatcher. The first Consumer that opens an IA must use \fBDAT_HANDLE_NULL\fR
  88 because no EVD can yet exist for the requested \fIia_name_ptr\fR.
  89 .sp
  90 .LP
  91 The Asynchronous Event Dispatcher (\fIasync_evd_handle\fR) is created with no
  92 CNO (\fBDAT_HANDLE_NULL\fR). Consumers can change these values using
  93 \fBdat_evd_modify_cno\fR(3DAT). The Consumer can modify parameters of the Event
  94 Dispatcher using \fBdat_evd_resize\fR(3DAT) and \fBdat_evd_modify_cno()\fR.
  95 .sp
  96 .LP
  97 The Provider is required to provide a queue size at least equal to
  98 \fIasync_evd_min_qlen\fR, but is free to provide a larger queue size or
  99 dynamically enlarge the queue when needed. The Consumer can determine the
 100 actual queue size by querying the created Event Dispatcher instance.
 101 .sp
 102 .LP
 103 If \fIasync_evd_handle\fR is not \fBDAT_HANDLE_NULL\fR, the Provider does not
 104 create an Event Dispatcher for an asynchronous event and the Provider ignores
 105 the \fIasync_evd_min_qlen\fR value. The \fIasync_evd_handle\fR value passed in
 106 by the Consumer must be an asynchronous Event Dispatcher created for the same
 107 Provider (\fIia_name_ptr\fR). The Provider does not have to check for the
 108 validity of the Consumer passed in \fIasync_evd_handle\fR. It is the Consumer
 109 responsibility to guarantee that \fIasync_evd_handle\fR is valid and for this
 110 Provider. How the \fIasync_evd_handle\fR is passed between DAT Consumers is out
 111 of scope of the DAT specification. If the Provider determines that the
 112 Consumer-provided \fIasync_evd_handle\fR is invalid, the operation fails and
 113 returns \fBDAT_INVALID_HANDLE\fR. The \fIasync_evd_handle\fR remains unchanged,
 114 so the returned \fIasync_evd_handle\fR is the same the Consumer passed in. All
 115 asynchronous notifications for the open instance of the IA are directed by the
 116 Provider to the Consumer passed in Asynchronous Event Dispatcher specified by
 117 \fIasync_evd_handle\fR.
 118 .sp
 119 .LP
 120 Consumer can specify the value of \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that
 121 there exists an event dispatcher somewhere else on the host, in user or kernel
 122 space, for asynchronous event notifications. It is up to the Consumer to ensure
 123 that this event dispatcher is unique and unambiguous. A special handle may be
 124 returned for the Asynchronous Event Dispatcher for this scenario,
 125 \fBDAT_EVD_OUT_OF_SCOPE\fR, to indicate that there is a default Event
 126 Dispatcher assigned for this Interface Adapter, but that it is not in a scope
 127 where this Consumer may directly invoke it.
 128 .sp
 129 .LP
 130 The Asynchronous Event Dispatcher is an Object of both the Provider and IA.
 131 Each Asynchronous Event Dispatcher bound to an IA instance is notified of all
 132 asynchronous events, such that binding multiple Asynchronous Event Dispatchers
 133 degrades performance by duplicating asynchronous event notifications for all
 134 Asynchronous Event Dispatchers. Also, transport and memory resources can be
 135 consumed per Event Dispatcher bound to an IA
 136 .sp
 137 .LP
 138 As with all Event Dispatchers, the Consumer is responsible for synchronizing
 139 access to the event queue.
 140 .sp
 141 .LP
 142 Valid IA names are obtained from \fBdat_registry_list_providers\fR(3DAT).
 143 .SH RETURN VALUES
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBDAT_SUCCESS\fR\fR
 148 .ad
 149 .RS 30n
 150 The operation was successful.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
 157 .ad
 158 .RS 30n
 159 The operation failed due to resource limitations.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 166 .ad
 167 .RS 30n
 168 Invalid parameter.
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBDAT_PROVIDER_NOT_FOUND\fR\fR
 175 .ad
 176 .RS 30n
 177 The specified provider was not registered in the registry.
 178 .RE
 179
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBDAT_INVALID_HANDLE\fR\fR
 184 .ad
 185 .RS 30n
 186 Invalid DAT handle; async_evd_handle is invalid.
 187 .RE
 188
 189 .SH USAGE
 190 .sp
 191 .LP
 192 The \fBdat_ia_open()\fR function is the root method for the Provider, and,
 193 thus, all Objects. It is the root handle through which the Consumer obtains all
 194 other DAT handles. When the Consumer closes its handle, all its DAT Objects are
 195 released.
 196 .sp
 197 .LP
 198 The \fBdat_ia_open()\fR function is the workhorse method that provides an IA
 199 instance. It can also initialize the Provider library or do any other
 200 registry-specific functions.
 201 .sp
 202 .LP
 203 The \fBdat_ia_open()\fR function creates a unique handle for the IA to the
 204 Consumer. All further DAT Objects created for this Consumer reference this
 205 handle as their owner.
 206 .sp
 207 .LP
 208 The \fBdat_ia_open()\fR function can use a reference count for the Provider
 209 Library to ensure that the Provider Library cannot be removed when it is in use
 210 by a DAT Consumer.
 211 .SH ATTRIBUTES
 212 .sp
 213 .LP
 214 See \fBattributes\fR(5) for descriptions of the following attributes:
 215 .sp
 216
 217 .sp
 218 .TS
 219 box;
 220 c | c
 221 l | l .
 222 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 223 _
 224 Interface Stability     Committed
 225 _
 226 MT-Level        Safe
 227 _
 228 Standard        uDAPL, 1.1, 1.2 (except \fBRO_AWARE_\fR)
 229 .TE
 230
 231 .SH SEE ALSO
 232 .sp
 233 .LP
 234 \fBdat_evd_modify_cno\fR(3DAT), \fBdat_evd_resize\fR(3DAT),
 235 \fBdat_ia_close\fR(3DAT), \fBdat_registry_list_providers\fR(3DAT),
 236 \fBlibdat\fR(3LIB), \fBattributes\fR(5)