share/man/man3dat/dat_ep_post_send.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_POST_SEND 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_ep_post_send \- transfer data to the remote side
  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_ep_post_send (
  18     IN    DAT_EP_HANDLE        ep_handle,
  19     IN    DAT_COUNT            num_segments,
  20     IN    DAT_LMR_TRIPLET      *local_iov,
  21     IN    DAT_DTO_COOKIE       user_cookie,
  22     IN    DAT_COMPLETION_FLAGS completion_flags
  23     )
  24 .fi
  25
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIep_handle\fR\fR
  31 .ad
  32 .RS 20n
  33 Handle for an instance of the Endpoint.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fInum_segments\fR\fR
  40 .ad
  41 .RS 20n
  42 Number of \fIlmr_triplets\fR in \fIlocal_iov\fR. Can be 0 for 0 size message.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIlocal_iov\fR\fR
  49 .ad
  50 .RS 20n
  51 I/O Vector that specifies the local buffer that contains data to be
  52 transferred. Can be \fINULL\fR for 0 size message.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIuser_cookie:\fR\fR
  59 .ad
  60 .RS 20n
  61 User-provided cookie that is returned to the Consumer at the completion of the
  62 send. Can be \fINULL\fR.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIcompletion_flags\fR\fR
  69 .ad
  70 .RS 20n
  71 Flags for posted Send. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is 0x00.
  72 Other values are as follows:
  73 .sp
  74 .ne 2
  75 .na
  76 \fBCompletion Suppression\fR
  77 .ad
  78 .RS 30n
  79 \fBDAT_COMPLETION_SUPPRESS_FLAG\fR
  80 .sp
  81 .ne 2
  82 .na
  83 \fB0x01\fR
  84 .ad
  85 .RS 8n
  86 Suppress successful Completion.
  87 .RE
  88
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fBSolicited Wait\fR
  95 .ad
  96 .RS 30n
  97 \fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR
  98 .sp
  99 .ne 2
 100 .na
 101 \fB0x02\fR
 102 .ad
 103 .RS 8n
 104 Request for notification completion for matching receive on the other side of
 105 the connection.
 106 .RE
 107
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fBNotification of Completion\fR
 114 .ad
 115 .RS 30n
 116 \fB\fR\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR
 117 .sp
 118 .ne 2
 119 .na
 120 \fB0x04\fR
 121 .ad
 122 .RS 8n
 123 Non-notification completion. Local Endpoint must be configured for Notification
 124 Suppression.
 125 .RE
 126
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fBBarrier Fence\fR
 133 .ad
 134 .RS 30n
 135 \fB\fR\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR
 136 .sp
 137 .ne 2
 138 .na
 139 \fB0x08\fR
 140 .ad
 141 .RS 8n
 142 Request for Barrier Fence.
 143 .RE
 144
 145 .RE
 146
 147 .RE
 148
 149 .SH DESCRIPTION
 150 .sp
 151 .LP
 152 The \fBdat_ep_post_send()\fR function requests a transfer of all the data from
 153 the \fIlocal_iov\fR over the connection of the \fIep_handle\fR Endpoint to the
 154 remote side.
 155 .sp
 156 .LP
 157 The \fInum_segments\fR parameter specifies the number of segments in the
 158 \fIlocal_iov\fR. The \fIlocal_iov\fR segments are traversed in the I/O Vector
 159 order until all the data is transferred.
 160 .sp
 161 .LP
 162 A Consumer cannot modify the \fIlocal_iov\fR or its content until the DTO is
 163 completed. When a Consumer does not adhere to this rule, the behavior of the
 164 Provider and the underlying Transport is not defined. Providers that allow
 165 Consumers to get ownership of the \fIlocal_iov\fR back after the
 166 \fBdat_ep_post_send()\fR returns should document this behavior and also specify
 167 its support in Provider attributes. This behavior allows Consumers full control
 168 of the \fIlocal_iov\fR, but not the memory it specifies after
 169 \fBdat_ep_post_send()\fR returns. Because this behavior is not guaranteed by
 170 all Providers, portable Consumers should not rely on this behavior. Consumers
 171 should not rely on the Provider copying \fIlocal_iov\fR information.
 172 .sp
 173 .LP
 174 The \fBDAT_SUCCESS\fR return of the \fBdat_ep_post_send()\fR is at least the
 175 equivalent of posting a Send operation directly by native Transport. Providers
 176 should avoid resource allocation as part of \fBdat_ep_post_send()\fR to ensure
 177 that this operation is nonblocking and thread safe for an UpCall.
 178 .sp
 179 .LP
 180 The completion of the posted Send is reported to the Consumer asynchronously
 181 through a DTO Completion event based on the specified \fIcompletion_flags\fR
 182 value. The value of \fBDAT_COMPLETION _UNSIGNALLED_FLAG\fR is only valid if the
 183 Endpoint Request Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR.
 184 Otherwise, \fBDAT_INVALID_PARAMETER\fR is returned.
 185 .sp
 186 .LP
 187 The \fIuser_cookie\fR allows Consumers to have unique identifiers for each DTO.
 188 These identifiers are completely under user control and are opaque to the
 189 Provider. There is no requirement on the Consumer that the value
 190 \fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is
 191 returned to the Consumer in the Completion event for the posted Send.
 192 .sp
 193 .LP
 194 The operation is valid for the Endpoint in the \fBDAT_EP_STATE_CONNECTED\fR and
 195 \fBDAT_EP_STATE_DISCONNECTED\fR states. If the operation returns successfully
 196 for the Endpoint in the \fBDAT_EP_STATE_DISCONNECTED\fR state, the posted Send
 197 is immediately flushed to \fIrequest_evd_handle\fR.
 198 .SH RETURN VALUES
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBDAT_SUCCESS\fR\fR
 203 .ad
 204 .RS 30n
 205 The operation was successful.
 206 .RE
 207
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
 212 .ad
 213 .RS 30n
 214 The operation failed due to resource limitations.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 221 .ad
 222 .RS 30n
 223 Invalid parameter. For example, one of the IOV segments pointed to a memory
 224 outside its LMR.
 225 .RE
 226
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fBDAT_INVALID_HANDLE\fR\fR
 231 .ad
 232 .RS 30n
 233 The \fIep_handle\fR parameter is invalid.
 234 .RE
 235
 236 .sp
 237 .ne 2
 238 .na
 239 \fB\fBDAT_INVALID_STATE\fR\fR
 240 .ad
 241 .RS 30n
 242 A parameter is in an invalid state. Endpoint was not in the
 243 \fBDAT_EP_STATE_CONNECTED\fR or \fBDAT_EP_STATE_DISCONNECTED\fR state.
 244 .RE
 245
 246 .sp
 247 .ne 2
 248 .na
 249 \fB\fBDAT_PROTECTION_VIOLATION\fR\fR
 250 .ad
 251 .RS 30n
 252 Protection violation for local or remote memory access. Protection Zone
 253 mismatch between an LMR of one of the \fIlocal_iov\fR segments and the local
 254 Endpoint.
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR
 261 .ad
 262 .RS 30n
 263 Privileges violation for local or remote memory access. One of the LMRs used in
 264 \fIlocal_iov\fR was either invalid or did not have the local read privileges.
 265 .RE
 266
 267 .SH USAGE
 268 .sp
 269 .LP
 270 For best Send operation performance, the Consumer should align each buffer
 271 segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of the
 272 Provider. For portable applications, the Consumer should align each buffer
 273 segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR.
 274 .SH ATTRIBUTES
 275 .sp
 276 .LP
 277 See \fBattributes\fR(5) for descriptions of the following attributes:
 278 .sp
 279
 280 .sp
 281 .TS
 282 box;
 283 c | c
 284 l | l .
 285 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 286 _
 287 Interface Stability     Standard: uDAPL, 1.1, 1.2
 288 _
 289 MT-Level        Unsafe
 290 .TE
 291
 292 .SH SEE ALSO
 293 .sp
 294 .LP
 295 \fBlibdat\fR(3LIB), \fBattributes\fR(5)