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)