dmnetsend(3dm)
dmNetSend, dmNetRecv - send and receive DMbuffers
As shipped in IRIX 6.5.7. Last changed in IRIX 6.5.5.
NAME dmNetSend, dmNetRecv - send and receive DMbuffers 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 DMnetconnection. dmNetRecv returns a filled DMbuffer from the open data connection specified by DMnetconnection. The DMbuffer is allocated from the DMbufferpool which had been previous registered with the call to dmNetRegisterPool or is pre-allocated and passed into dmNetRecv, after a call to dmNetRegisterBuffer . TIMESTAMPS If the caller does not set the MSC associated with the DMbuffer , 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 DM_SUCCESS or DM_FAILURE. dmNetSend and dmNetRecv fail if one or more of the following are true: EINVAL connection is not a valid connection descriptor. ESHUTDOWN the peer has closed the underlying network connection. In addition, 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). EPIPE receiver died in the middle of a write system call (dmNet catches SIGPIPE and reports errno as EPIPE). 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. ENODATA end of file reached - no more data available. 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 dmNetDataFd to determine the likelihood that data is ready. It should go without saying that they must also carefully check the return and error values. Error values are may be obtained through dmGetError Most applications will want to call these routines in a separate thread. SEE ALSO dmBufferAllocate(3dm), dmGetUSTCurrentTimePair(3dm), dmNetDataFd(3dm), dmNetRegisterPool(3dm), dmNetRegisterBuffer(3dm), select(2), xntpd(1L), timed(1M)