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