Manual Pages for UNIX Operating System command usage for man dat_ep_post_send

Direct Access Transport Library Functions  dat_ep_post_send(3DAT)



NAME
     dat_ep_post_send - transfer data to the remote side

SYNOPSIS
     cc [ flag... ] file... -ldat [ library... ]
     #include 

     DAT_RETURN
         dat_ep_post_send (
         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 0 size message.


     local_iov           I/O  Vector  that  specifies  the  local
                         buffer   that   contains   data   to  be
                         transferred. Can be NULL for 0 size mes-
                         sage.


     user_cookie:        User-provided cookie that is returned to
                         the  Consumer  at  the completion of the
                         send. Can be NULL.


     completion_flags    Flags  for  posted  Send.  The   default
                         DAT_COMPLETION_DEFAULT_FLAG   is   0x00.
                         Other values are as follows:

                         Completion Suppression        DAT_COMPLETION_SUPPRESS_FLAG

                                                       0x01    Suppress
                                                               suc-
                                                               cess-
                                                               ful
                                                               Com-
                                                               ple-
                                                               tion.






SunOS 5.11          Last change: 16 Jul 2004                    1






Direct Access Transport Library Functions  dat_ep_post_send(3DAT)



                         Solicited Wait                DAT_COMPLETION_SOLICITED_WAIT_FLAG

                                                       0x02    Request
                                                               for
                                                               notif-
                                                               i-
                                                               ca-
                                                               tion
                                                               com-
                                                               ple-
                                                               tion
                                                               for
                                                               match-
                                                               ing
                                                               receive
                                                               on
                                                               the
                                                               other
                                                               side
                                                               of
                                                               the
                                                               con-
                                                               nec-
                                                               tion.



                         Notification of Completion    DAT_COMPLETION_UNSIGNALLED_FLAG

                                                       0x04    Non-
                                                               notification
                                                               com-
                                                               ple-
                                                               tion.
                                                               Local
                                                               End-
                                                               point
                                                               must
                                                               be
                                                               con-
                                                               fig-
                                                               ured
                                                               for
                                                               Notif-
                                                               i-
                                                               ca-
                                                               tion
                                                               Suppres-
                                                               sion.






SunOS 5.11          Last change: 16 Jul 2004                    2






Direct Access Transport Library Functions  dat_ep_post_send(3DAT)



                         Barrier Fence                 DAT_COMPLETION_BARRIER_FENCE_FLAG

                                                       0x08    Request
                                                               for
                                                               Bar-
                                                               rier
                                                               Fence.




DESCRIPTION
     The dat_ep_post_send() function requests a transfer  of  all
     the  data  from  the  local_iov  over  the connection of the
     ep_handle Endpoint to the remote side.


     The num_segments parameter specifies the number of  segments
     in  the  local_iov.  The local_iov segments are traversed in
     the I/O Vector order until all the data is transferred.


     A Consumer cannot modify the local_iov or its content  until
     the  DTO  is  completed.  When a Consumer does not adhere to
     this rule, the behavior of the Provider and  the  underlying
     Transport  is not defined. Providers that allow Consumers to
     get   ownership   of   the   local_iov   back   after    the
     dat_ep_post_send() returns should document this behavior and
     also  specify  its  support  in  Provider  attributes.  This
     behavior allows Consumers full control of the local_iov, but
     not  the  memory  it  specifies   after   dat_ep_post_send()
     returns. Because this behavior is not guaranteed by all Pro-
     viders, portable Consumers should not rely on this behavior.
     Consumers  should not rely on the Provider copying local_iov
     information.


     The DAT_SUCCESS return of the dat_ep_post_send() is at least
     the  equivalent  of  posting  a  Send  operation directly by
     native Transport. Providers should avoid resource allocation
     as  part of dat_ep_post_send() to ensure that this operation
     is nonblocking and thread safe for an UpCall.


     The completion of the posted Send is reported to the  Consu-
     mer  asynchronously  through a DTO Completion event based on
     the  specified  completion_flags   value.   The   value   of
     DAT_COMPLETION  _UNSIGNALLED_FLAG  is only valid if the End-
     point           Request           Completion           Flags
     DAT_COMPLETION_UNSIGNALLED_FLAG.                  Otherwise,
     DAT_INVALID_PARAMETER is returned.




SunOS 5.11          Last change: 16 Jul 2004                    3






Direct Access Transport Library Functions  dat_ep_post_send(3DAT)



     The user_cookie allows Consumers to have unique  identifiers
     for  each  DTO.  These identifiers are completely under user
     control 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 Send.


     The  operation  is   valid   for   the   Endpoint   in   the
     DAT_EP_STATE_CONNECTED and DAT_EP_STATE_DISCONNECTED states.
     If the operation returns successfully for  the  Endpoint  in
     the  DAT_EP_STATE_DISCONNECTED  state,  the  posted  Send is
     immediately flushed to request_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.


     DAT_INVALID_HANDLE            The  ep_handle  parameter   is
                                   invalid.


     DAT_INVALID_STATE             A parameter is in  an  invalid
                                   state. Endpoint was not in the
                                   DAT_EP_STATE_CONNECTED      or
                                   DAT_EP_STATE_DISCONNECTED
                                   state.


     DAT_PROTECTION_VIOLATION      Protection violation for local
                                   or  remote memory access. Pro-
                                   tection Zone mismatch  between
                                   an LMR of one of the local_iov
                                   segments and  the  local  End-
                                   point.


     DAT_PRIVILEGES_VIOLATION      Privileges violation for local
                                   or  remote  memory access. One
                                   of the LMRs used in  local_iov
                                   was  either invalid or did not
                                   have    the     local     read



SunOS 5.11          Last change: 16 Jul 2004                    4






Direct Access Transport Library Functions  dat_ep_post_send(3DAT)



                                   privileges.


USAGE
     For best Send operation  performance,  the  Consumer  should
     align 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 of
     local_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                    5