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
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
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)
|
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
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
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)
|