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)