t_rcvudata(NET)

t_rcvudata -- receive a data unit

Synopsis

cc [options] file -lnsl

#include <xti.h>

int t_rcvudata(int fd, struct t_unitdata unitdata, int flags);

Description

This function is a TLI/XTI data transfer routine used in connectionless mode to receive a data unit from another transport user. Data is received through the transport endpoint specified by fd. On return, unitdata contains the information associated with the data unit, and flags points to a value that indicates whether the complete data unit was received.

This function is a service of connectionless transport providers and is supported only if the provider returned service type T_CLTS on t_open or t_getinfo.

Parameters

fd: the file descriptor for the transport endpoint through which the data will be received.
unitdata: points to the t_unitdata structure associated with the received data unit.
flags: points to a value set on return if the complete data unit was not received.

Structure definitions

The unitdata argument points to a t_unitdata structure containing the following members:

   struct netbuf addr;     /* address      */
   struct netbuf opt;      /* options      */
   struct netbuf udata;    /* user data    */

netbuf is described in intro(NET). The maxlen field of addr, opt, and udata must be set before issuing this function to indicate the maximum size of the buffer for each.

On return from this call, addr specifies the protocol address of the sending user, opt identifies protocol-specific options that were associated with this data unit, and udata specifies the user data that was received.

If the buffer defined in the udata field of unitdata is not large enough to hold the current data unit, the buffer will be filled and T_MORE will be set in flags on return to indicate that another t_rcvudata should be issued to retrieve the rest of the data unit. Subsequent t_rcvudata call(s) will return 0 for the length of the address and options until the full data unit has been received.

State transitions

On entry, T_IDLE; unchanged on exit.

Files

/usr/lib/libxti.so: X/Open^® Transport Interface Library (shared object)
/usr/lib/libnsl.so: Network Services Library (shared object)

Usage

By default, t_rcvudata operates in synchronous mode and will wait for a data unit to arrive if none is currently available. However, if O_NONBLOCK is set (via t_open or fcntl), t_rcvudata will execute in asynchronous mode and will fail if no data units are available.

Return values

t_rcvudata returns 0 on successful completion and -1 on failure and t_errno is set to indicate the error.

Errors

On failure, t_errno may be set to one of the following:

TBADF: The specified file descriptor does not refer to a transport endpoint.
TNODATA: O_NONBLOCK was set, but no data units are currently available from the transport provider.
TBUFOVFLW: The number of bytes (maxlen) allocated for an incoming argument is greater than zero but not sufficient to store the value of that argument. The unit data information to be returned in unitdata will be discarded.
TLOOK: An asynchronous event has occurred on the transport endpoint specified by fd and requires immediate attention.
TNOTSUPPORT: This function is not supported by the underlying transport provider.
TOUTSTATE: The function was issued in the wrong sequence on the transport endpoint referenced by fd.
TSYSERR: A system error has occurred during execution of this function.
TPROTO: A communication problem has been detected with the transport provider and there is no other value of t_errno to describe the error condition.

References

fcntl(S), intro(NET), t_getinfo(NET), t_open(NET), t_rcvuderr(NET), t_sndudata(NET)