t_rcvudata - Receive a data unit
#include <xti.h>
int t_rcvudata(
int fd,
struct t_unitdata *unitdata,
int *flags );
XTI Library (libxti.a)
Interfaces documented on this reference page conform to
industry standards as follows:
t_rcvudata(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
The following table summarizes the relevance of input and
output parameter 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 meaningful parameter. The content of the object
pointed to by y is meaningful. 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 following 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 referenced
by this member is defined in the xti.h include file
and has the following members: Specifies the maximum byte
length of the data buffer. Specifies the actual byte
length of the data written to the buffer. Points to the
buffer location. Specifies a buffer for protocol-specific
parameters associated with the data unit. Specifies
parameters 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
unitdata->addr.maxlen, unitdata->opt.maxlen, and
unitdata->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
parameter 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_rcvudata() call must immediately be made
to receive additional current 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.
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 transport 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 unavailable, control
is immediately returned to the caller.
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.
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 supported 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).
The t_rcvudata() function can only be called in the T_IDLE
transport provider state.
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)
[ Back ] | 