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