Direct Access Transport Library Functions dat_ep_post_recv(3DAT)
NAME
dat_ep_post_recv - receive data over the connection of the
EndpointSYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DAT_RETURN
dat_ep_post_recv (
IN DAT_EP_HANDLE ep_handle,
IN DAT_COUNT num_segments,
IN DAT_LMR_TRIPLET *local_iov,
IN DAT_DTO_COOKIE user_cookie,
IN DAT_COMPLETION_FLAGS completion_flags
)PARAMETERS
ep_handle Handle for an instance of the Endpoint.
num_segments Number of lmr_triplets in local_iov. Can
be 0 for receiving a 0 size message.local_iov I/O Vector that specifies the local
buffer to be filled. Can be NULL for receiving a 0 size message.user_cookie: User-provided cookie that is returned to
the Consumer at the completion of the Receive DTO. Can be NULL.completion_flags Flags for posted Receive. The default
DAT_COMPLETION_DEFAULT_FLAG is 0x00.
Other values are as follows:Notification of Completion DAT_COMPLETION_UNSIGNALLED_FLAG
0x04 Non-
notificationcom-
ple-
tion. LocalEnd-
point must beSunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions dat_ep_post_recv(3DAT)
con-
fig-
ured forUnsig-
naledCom-
pletion-
No-
tif-
i-
ca-
tionSuppres-
sion.DESCRIPTION
The dat_ep_post_recv() function requests the receive of the
data over the connection of the ep_handle Endpoint of the
incoming message into the local_iov.
The num_segments parameter specifies the number of segments
in the local_iov. The local_iov segments are filled in the
I/O Vector order until the whole message is received. This
ensures that all the "front" segments of the local_iov I/O
Vector are completely filled, only one segment is partially filled, if needed, and all segments that follow it are not filled at all.The user_cookie allows Consumers to have unique identifiers
for each DTO. These identifiers are completely under usercontrol and are opaque to the Provider. There is no require-
ment on the Consumer that the value user_cookie should be
unique for each DTO. The user_cookie is returned to the Con-
sumer in the Completion event for the posted Receive.The completion of the posted Receive is reported to the Con-
sumer asynchronously through a DTO Completion event based on the configuration of the connection for Solicited Wait andthe specified completion_flags value for the matching Send.
The value of DAT_COMPLETION _UNSIGNALLED_FLAG is only valid
if the Endpoint Recv Completion FlagsDAT_COMPLETION_UNSIGNALLED_FLAG. Otherwise,
DAT_INVALID_PARAMETER is returned.
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions dat_ep_post_recv(3DAT)
A Consumer must not modify the local_iov or its content
until the DTO is completed. When a Consumer does not adhereto this rule, the behavior of the Provider and the underly-
ing Transport is not defined. Providers that allow Consumersto get ownership of the local_iov but not the memory it
specified back after the dat_ep_post_recv() returns should
document this behavior and also specify its support in Pro-
vider attributes. This behavior allows Consumer full controlof the local_iov content after dat_ep_post_recv() returns.
Because this behavior is not guaranteed by all Providers,portable Consumers should not rely on this behavior. Consu-
mers shouldnot rely on the Provider copying local_iov
information.The DAT_SUCCESS return of the dat_ep_post_recv() is at least
the equivalent of posting a Receive operation directly by native Transport. Providers should avoid resource allocationas part of dat_ep_post_recv() to ensure that this operation
is nonblocking and thread safe for an UpCall. If the size of an incoming message is larger than the sizeof the local_iov, the reported status of the posted Receive
DTO in the corresponding Completion DTO event isDAT_DTO_LENGTH_ERROR. If the reported status of the Comple-
tion DTO event corresponding to the posted Receive DTO isnot DAT_DTO_SUCCESS, the content of the local_iov is not
defined. The operation is valid for all states of the Endpoint. The actual data transfer does not take place until the Endpointis in the DAT_EP_STATE_CONNECTED state. The operation on the
Endpoint in DAT_EP_STATE_DISCONNECTED is allowed. If the
operation returns successfully, the posted Recv is immedi-
ately flushed to recv_evd_handle.
RETURN VALUES
DAT_SUCCESS The operation was successful.
DAT_INSUFFICIENT_RESOURCES The operation failed due to
resource limitations.DAT_INVALID_PARAMETER Invalid parameter. For exam-
ple, one of the IOV segments pointed to a memory outside its LMR.SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions dat_ep_post_recv(3DAT)
DAT_INVALID_HANDLE The ep_handle parameter is
invalid.DAT_PROTECTION_VIOLATION Protection violation for local
or remote memory access. Pro-
tection Zone mismatch betweenan LMR of one of the local_iov
segments and the local End-
point.DAT_PRIVILEGES_VIOLATION Privileges violation for local
or remote memory access. Oneof the LMRs used in local_iov
was either invalid or did not have the local read privileges.USAGE
For best Recv operation performance, the Consumer shouldalign each buffer segment of local_iov to the Optimal Buffer
Alignment attribute of the Provider. For portable applica-
tions, the Consumer should align each buffer segment oflocal_iov to the DAT_OPTIMAL_ALIGNMENT.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Unsafe |
|_____________________________|_____________________________|
| Standard | uDAPL, 1.1, 1.2 ||_____________________________|_____________________________|
SEE ALSO
libdat(3LIB), attributes(5)SunOS 5.11 Last change: 16 Jul 2004 4