usr/src/man/man3dat/dat_ep_post_recv.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_RECV 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_ep_post_recv \- receive data over the connection of the Endpoint
  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_recv (
  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 receiving a 0
  43 size message.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIlocal_iov\fR\fR
  50 .ad
  51 .RS 20n
  52 I/O Vector that specifies the local buffer to be filled. Can be \fINULL\fR for
  53 receiving a 0 size message.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIuser_cookie:\fR\fR
  60 .ad
  61 .RS 20n
  62 User-provided cookie that is returned to the Consumer at the completion of the
  63 Receive DTO. Can be \fINULL\fR.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIcompletion_flags\fR\fR
  70 .ad
  71 .RS 20n
  72 Flags for posted Receive. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is
  73 0x00. Other values are as follows:
  74 .sp
  75 .ne 2
  76 .na
  77 \fBNotification of Completion\fR
  78 .ad
  79 .RS 30n
  80 \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR
  81 .sp
  82 .ne 2
  83 .na
  84 \fB0x04\fR
  85 .ad
  86 .RS 8n
  87 Non-notification completion. Local Endpoint must be configured for Unsignaled
  88 CompletionNotification Suppression.
  89 .RE
  90
  91 .RE
  92
  93 .RE
  94
  95 .SH DESCRIPTION
  96 .sp
  97 .LP
  98 The \fBdat_ep_post_recv()\fR function requests the receive of the data over the
  99 connection of the \fIep_handle\fR Endpoint of the incoming message into the
 100 \fIlocal_iov\fR.
 101 .sp
 102 .LP
 103 The \fInum_segments\fR parameter specifies the number of segments in the
 104 \fIlocal_iov\fR. The \fIlocal_iov\fR segments are filled in the I/O Vector
 105 order until the whole message is received. This ensures that all the "front"
 106 segments of the \fIlocal_iov\fR I/O Vector are completely filled, only one
 107 segment is partially filled, if needed, and all segments that follow it are not
 108 filled at all.
 109 .sp
 110 .LP
 111 The \fIuser_cookie\fR allows Consumers to have unique identifiers for each DTO.
 112 These identifiers are completely under user control and are opaque to the
 113 Provider. There is no requirement on the Consumer that the value
 114 \fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is
 115 returned to the Consumer in the Completion event for the posted Receive.
 116 .sp
 117 .LP
 118 The completion of the posted Receive is reported to the Consumer asynchronously
 119 through a DTO Completion event based on the configuration of the connection for
 120 Solicited Wait and the specified \fIcompletion_flags\fR value for the matching
 121 Send. The value of \fBDAT_COMPLETION _UNSIGNALLED_FLAG\fR is only valid if the
 122 Endpoint Recv Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR.
 123 Otherwise, \fBDAT_INVALID_PARAMETER\fR is returned.
 124 .sp
 125 .LP
 126 A Consumer must not modify the \fIlocal_iov\fR or its content until the DTO is
 127 completed. When a Consumer does not adhere to this rule, the behavior of the
 128 Provider and the underlying Transport is not defined. Providers that allow
 129 Consumers to get ownership of the \fIlocal_iov\fR but not the memory it
 130 specified back after the \fBdat_ep_post_recv()\fR returns should document this
 131 behavior and also specify its support in Provider attributes. This behavior
 132 allows Consumer full control of the \fIlocal_iov\fR content after
 133 \fBdat_ep_post_recv()\fR returns. Because this behavior is not guaranteed by
 134 all Providers, portable Consumers should not rely on this behavior. Consumers
 135 shouldnot rely on the Provider copying \fIlocal_iov\fR information.
 136 .sp
 137 .LP
 138 The \fBDAT_SUCCESS\fR return of the \fBdat_ep_post_recv()\fR is at least the
 139 equivalent of posting a Receive operation directly by native Transport.
 140 Providers should avoid resource allocation as part of \fBdat_ep_post_recv()\fR
 141 to ensure that this operation is nonblocking and thread safe for an UpCall.
 142 .sp
 143 .LP
 144 If the size of an incoming message is larger than the size of the
 145 \fIlocal_iov\fR, the reported status of the posted Receive DTO in the
 146 corresponding Completion DTO event is \fBDAT_DTO_LENGTH_ERROR\fR. If the
 147 reported status of the Completion DTO event corresponding to the posted Receive
 148 DTO is not \fBDAT_DTO_SUCCESS\fR, the content of the \fIlocal_iov\fR is not
 149 defined.
 150 .sp
 151 .LP
 152 The operation is valid for all states of the Endpoint. The actual data transfer
 153 does not take place until the Endpoint is in the \fBDAT_EP_STATE_CONNECTED\fR
 154 state. The operation on the Endpoint in \fBDAT_EP_STATE_DISCONNECTED\fR is
 155 allowed. If the operation returns successfully, the posted Recv is immediately
 156 flushed to \fIrecv_evd_handle\fR.
 157 .SH RETURN VALUES
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBDAT_SUCCESS\fR\fR
 162 .ad
 163 .RS 30n
 164 The operation was successful.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
 171 .ad
 172 .RS 30n
 173 The operation failed due to resource limitations.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 180 .ad
 181 .RS 30n
 182 Invalid parameter. For example, one of the IOV segments pointed to a memory
 183 outside its LMR.
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBDAT_INVALID_HANDLE\fR\fR
 190 .ad
 191 .RS 30n
 192 The \fIep_handle\fR parameter is invalid.
 193 .RE
 194
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBDAT_PROTECTION_VIOLATION\fR\fR
 199 .ad
 200 .RS 30n
 201 Protection violation for local or remote memory access. Protection Zone
 202 mismatch between an LMR of one of the \fIlocal_iov\fR segments and the local
 203 Endpoint.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR
 210 .ad
 211 .RS 30n
 212 Privileges violation for local or remote memory access. One of the LMRs used in
 213 \fIlocal_iov\fR was either invalid or did not have the local read privileges.
 214 .RE
 215
 216 .SH USAGE
 217 .sp
 218 .LP
 219 For best Recv operation performance, the Consumer should align each buffer
 220 segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of the
 221 Provider. For portable applications, the Consumer should align each buffer
 222 segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR.
 223 .SH ATTRIBUTES
 224 .sp
 225 .LP
 226 See \fBattributes\fR(5) for descriptions of the following attributes:
 227 .sp
 228
 229 .sp
 230 .TS
 231 box;
 232 c | c
 233 l | l .
 234 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 235 _
 236 Interface Stability     Standard: uDAPL, 1.1, 1.2
 237 _
 238 MT-Level        Unsafe
 239 .TE
 240
 241 .SH SEE ALSO
 242 .sp
 243 .LP
 244 \fBlibdat\fR(3LIB), \fBattributes\fR(5)