 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
t_rcvudata(3)
NAME
t_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 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.
PARAMETERS
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:
y This is a meaningful parameter.
n This is not a meaningful parameter.
(y) The content of the object pointed to by y is meaningful.
fd Specifies a file descriptor returned by the t_open() function that
identifies the transport endpoint.
unitdata
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:
struct netbuf addr
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:
unsigned int maxlen
Specifies the maximum byte length of the data buffer.
unsigned int len
Specifies the actual byte length of the data written to the
buffer.
char *buf
Points to the buffer location.
struct netbuf opt
Specifies a buffer for protocol-specific parameters associated with
the data unit.
struct netbuf udata
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.
flags
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.
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 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.
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:
[TBADF]
The specified file descriptor does not refer to a transport endpoint.
[TNODATA]
Asynchronous mode is indicated because O_NONBLOCK was set, but no data
is currently available from the transport provider.
[TBUFOVFLW]
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.
[TLOOK]
An asynchronous event that requires immediate attention has occurred at
the transport endpoint specified by the fd parameter.
[TOUTSTATE]
The t_rcvudata() function was issued in the wrong sequence at the
transport endpoint referenced by the fd parameter.
[TSYSERR]
A system error occurred during execution of this function.
[TNOTSUPPORT]
This function is not supported by the underlying transport provider.
[TPROTO]
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|