t_rcvudata(3)t_rcvudata(3)NAMEt_rcvudata - Receive a data unit
SYNOPSIS
#include <xti.h>
int t_rcvudata(
int fd,
struct t_unitdata *unitdata,
int *flags );
LIBRARY
XTI Library (libxti.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
t_rcvudata(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
The following table summarizes the relevance of input and output param‐
eter data before and after t_rcvudata() is called:
──────────────────────────────────────────────────
Parameters Before Call After Call
──────────────────────────────────────────────────
fd y n
unitdata->addr.maxlen y n
unitdata->addr.len n y
unitdata->addr.buf o (o)
unitdata->opt.maxlen y n
unitdata->opt.len n y
unitdata->opt.buf o (o)
unitdata->udata.maxlen y n
unitdata->udata.len n y
unitdata->udata.buf o (o)
flags n y
──────────────────────────────────────────────────
Notes to Table: This is a meaningful parameter. This is not a meaning‐
ful parameter. The content of the object pointed to by y is meaning‐
ful. Specifies a file descriptor returned by the t_open() function
that identifies the transport endpoint. Points to a type t_unitdata
structure used to specify information required by the transport
provider user to receive a data unit through the transport endpoint
specified by the fd parameter. The t_unitdata structure has the follow‐
ing members: References a buffer for protocol address information
required from the transport endpoint specified by the fd parameter.
This is the address of the sender. The type netbuf structure refer‐
enced by this member is defined in the xti.h include file and has the
following members: Specifies the maximum byte length of the data buf‐
fer. Specifies the actual byte length of the data written to the buf‐
fer. Points to the buffer location. Specifies a buffer for protocol-
specific parameters associated with the data unit. Specifies parame‐
ters for any user data unit that may be returned to the caller. This
is the data received.
Before the t_rcvudata() function is called the unit‐
data->addr.maxlen, unitdata->opt.maxlen, and unit‐
data->udata.maxlen parameters must be set to specify the maximum
byte length of the protocol address buffer, the protocol options
buffer, and the user data buffer, respectively. Points to a
flag integer that indicates that the complete data unit was not
received. Corresponding values and symbolic names for flags are
defined in the xti.h include file (see the t_optmgmt() and
t_rcv() functions). The option specified by this function is:
T_MORE.
When the data buffer specified by the unitdata->udata.buf param‐
eter is not large enough to hold the current user data unit, the
buffer is filled and this bit is set to indicate that another
t_rcvudata() function should be called to retrieve the rest of
the data unit.
The set state of this bit notifies the local transport user that
the received data unit is a fragment and that another data unit
is available. When this bit is set on return of this function,
another data unit must also be fetched with another t_rcvudata()
call. Each time this option is set on return, another t_rcvu‐
data() call must immediately be made to receive additional cur‐
rent data units. When the final data unit is received, this
option bit has a value of 0 (zero) on return.
Subsequent calls to the t_rcvudata() function return 0 (zero) as
the length of the address specified by the unitdata->addr.len
and unitdata->opt.len parameters until the full data unit has
been received.
DESCRIPTION
The t_rcvudata() function is an XTI connectionless service function
that is used to receive a data unit from a remote transport provider
user. By default, t_rcvudata() executes in the synchronous operating
mode. The t_rcvudata() function waits for data to arrive at the trans‐
port endpoint specified by fd before returning control to the transport
user who called this function.
However, when the transport endpoint, specified by the fd parameter,
has been previously opened with the O_NONBLOCK option set in the
t_open() or fcntl() function, the t_rcvudata() function executes in
asynchronous mode. In asynchronous mode, when a data unit is unavail‐
able, control is immediately returned to the caller.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned. Otherwise,
a value of -1 is returned and t_errno is set to indicate the error.
ERRORS
If the t_rcvudata() function fails, t_errno may be set to one of the
following values: The specified file descriptor does not refer to a
transport endpoint. Asynchronous mode is indicated because O_NONBLOCK
was set, but no data is currently available from the transport
provider. The number of bytes allocated for the incoming protocol
address or protocol options is not sufficient to store the information.
The unit data information normally returned to the unitdata parameter
is discarded. An asynchronous event that requires immediate attention
has occurred at the transport endpoint specified by the fd parameter.
The t_rcvudata() function was issued in the wrong sequence at the
transport endpoint referenced by the fd parameter. A system error
occurred during execution of this function. This function is not sup‐
ported by the underlying transport provider. This error indicates that
a communication problem has been detected between XTI and the transport
provider for which there is no other suitable XTI(t_errno).
VALID STATES
The t_rcvudata() function can only be called in the T_IDLE transport
provider state.
SEE ALSO
Functions: fcntl(2), t_alloc(3), t_open(3), t_optmgmt(3), t_rcv(3),
t_rcvuderr(3), t_sndudata(3)
Standards: standards(5)
Network Programmer's Guide
t_rcvudata(3)
