dmnetsend(3dm)

NAME
     dmNetSend, dmNetRecv - send and receive DMbuffers to and from a
     DMNetConnection

SYNOPSIS
     #include <dmedia/dmnet.h>

     DMstatus dmNetSend(DMNetConnection connection, DMbuffer dmbuf);

     DMstatus dmNetRecv(DMNetConnection connection, DMbuffer *dmbuf);

DESCRIPTION
     dmNetSend Sends the specified DMbuffer over the open data connection
     specified by connection.

     dmNetRecv Returns a filled DMbuffer from the open data connection
     specified by connection. The DMbuffer is allocated from the DMbufferpool
     which had been previous registered with the call to dmNetRegister.

TIMESTAMPS
     If the caller does not set the MSC associated with dmbuf, dmNetSend will
     provide a monotonically increasing value. To avoid possible confusion,
     callers should either always set an MSC value, or never set one.

     dmNetSend and dmNetRecv will cooperate in an attempt to make the UST
     value at the receiving end of a network connection equivalent to the UST
     value that was set at the sending end. This is accomplished by converting
     the UST to an equivalent "wall clock" value (via
     dmGetUSTCurrentTimePair).  This wall clock value is sent to the receiving
     end, which converts it back to an equivalent local UST value.  For this
     to be effective, the system clocks on the two machines must be
     synchronized by some external mechanism, such as xntpd or timed.

     If the sender sets the UST value to zero, dmNetSend and dmNetRecv will
     leave the value undisturbed. This is a convenient way for the sender to
     indicate that the receiver that the clock value is not to be trusted.

DIAGNOSTICS
     Depending on the underlying transport protocol, dmNetSend and dmNetRecv
     may or may not block (see the NOTE below).  They return success (via
     DM_SUCCESS) or failure (via DM_FAILURE).

     dmNetSend and dmNetRecv fail if one or more of the following are true:

     EINVAL         connection is not a valid connection descriptor.

     0              the peer has closed the underlying network connection.

          dmNetSend
          can fail as follows:  EBUSY insufficient internal resources to send
          the buffer (only when the underlying transport mechanism is using a
          DMS fifo; usually indicates that the receiver is not reading quickly
          enough).

     In addition, dmNetRecv can fail as follows:

     EBUSY          no data is available to be read (only when the underlying
                    transport mechanism returns filled DMbuffers via a DMS
                    fifo; currently only DMNET_LOCAL).

     ENOMEM         no DMbuffer could be allocated for the incoming data.

     ERANGE         the buffer allocated from the pool is too small to hold
                    the received data.

NOTE
     Depending on the underlying transport mechanism, the exact semantics of
     dmNetSend and dmNetRecv will vary. Some transports never block, instead
     returning EBUSY when there are insufficient resources or no waiting data.
     Others block if only some of the data has arrived on the network
     connection, or if the outgoing network connection is too full to deliver
     all of the data into the kernel.  Applications that are concerned about
     timely execution of these routines should use select and dmNetControlFd
     to determine the likelihood that data is ready. It should go without
     saying that they must also carefully check the return and error values.

     Most applications will want to call these routines in a separate thread.


     BUGS It's not a perfect world.

SEE ALSO
     dmBufferAllocate(3dm), dmGetUSTCurrentTimePair(3dm), dmNetControlFd(3dm),
     dmNetRegister(3dm), select(2), xntpd(1L), timed(1M)