 |
Click this button to go to the index for this section. |
t_rcv(3)
NAME
t_rcv - Receives normal data or expedited data on a connection
LIBRARY
XTI Library (libxti.a)
SYNOPSIS
#include <xti.h>
int t_rcv(
int fd,
char *buf,
unsigned nbytes,
int *flags) ;
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
t_rcv: XPG4-UNIX
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 parameters
before and after t_rcv() is called:
Parameters Before Call After Call
_____________________________________
fd y n
buf y (y)
nbytes y n
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 local transport endpoint where an active connection
exists.
buf Points to the receive data buffer where returned data is to be
written.
nbytes
Specifies the length in bytes of the received-data buffer pointed to
by the buf parameter.
flags
Points to an unsigned integer (least significant bit rightmost) whose
bits are flags that specify the action that must be taken by the
responding transport user when the t_rcv() function is processed.
Corresponding values and symbolic names for the following flag bits
are defined in the xti.h include file:
Bit Symbolic Name Meaning
______________________________________________________
0 T_MORE
When set, this bit notifies
the transport user that
received data is a fragment of
a Transport Service Data Unit
(TSDU) or Expedited Transport
Service Data Unit (ETSDU), and
that more data is available.
The rest of the TSDU or ETSDU
can be received through
further t_rcv() function
calls. Each time this flag is
set on return, another t_rcv()
call can receive additional
pieces of the TSDU or ETSDU.
When the final TSDU or ETSDU
is received, this flag bit has
a value of 0 (zero) on return.
When the transport provider
does not support TSDU or ETSDU
data exchanges (refer to the
t_open() and t_getinfo()
functions), the state of this
flag bit should be ignored.
1 T_EXPEDITED
When set, this bit notifies
the transport user that
received data is an ETSDU.
When the number of ETSDU data
bytes exceeds the value
specified by the nbytes
parameter, this flag bit and
the T_MORE flag bit are set on
return of the initial t_rcv()
call. Subsequent t_rcv() calls
issued to retrieve the rest of
the ETSDU have both these flag
bits set on return. When the
final piece of the ETSDU is
received, the T_MORE flag bit
has a value of 0 (zero) on
return.
When an ETSDU is received
during reception of a TSDU, no
remaining pieces of the TSDU
may be received until the
current ETSDU has been
completely received.
VALID STATES
The t_rcv() function can only be called in the T_DATAXFER and T_OUTREL
transport provider states.
DESCRIPTION
The t_rcv() function is an XTI connection-oriented service function that is
used to receive normal or expedited data. The transport endpoint through
which data arrives is specified by a file descriptor previously returned by
the t_open() function. By default, t_rcv() executes in the synchronous
operating mode. In synchronous mode t_rcv() waits for data to arrive even
when none is currently available before returning control to the calling
transport user.
When the transport endpoint, specified by the fd parameter, has been opened
with the O_NONBLOCK flag set in the t_open() or fcntl() functions, the
t_rcv() function executes in asynchronous mode. In asynchronous mode, when
no data is available, this function fails.
NOTES
In synchronous mode, the only way for a transport user to be notified of
the arrival of normal or expedited data is to call the t_rcv() function or
to check for states T_DATA or T_EXDATA using the t_look() function.
RETURN VALUES
Upon successful completion, the t_rcv() function returns the number of
bytes of data received. Otherwise, the value -1 is returned and t_errno is
set to indicate the error.
ERRORS
If the t_rcv() function fails, t_errno is set to one of the following
values:
[TBADF] The specified file descriptor does not refer to a valid transport
endpoint.
[TNODATA] Asynchronous mode is indicated because O_NONBLOCK was set, but no
data is currently available from the transport provider.
[TLOOK] An asynchronous event has occurred on this transport endpoint and
requires immediate attention (refer to t_look() function).
[TOUTSTATE]
The t_look() function was issued in the wrong sequence on the
transport endpoint referenced by the fd parameter.
[TSYSERR] A system error occurred during execution of t_look().
[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).
RELATED INFORMATION
Functions: fcntl(2), t_getinfo(3), t_look(3), t_open(3), t_snd(3).
Standards: standards(5).