t_rcv(3) Library Functions Manual 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(): XNS4.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 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 connec-
tion 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 fur-
ther 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() func-
tions), 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 speci-
fied by the nbytes parameter,
this flag bit and the T_MORE
flag bit are set on return of
the initial t_rcv() call. Sub-
sequent 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 dur-
ing reception of a TSDU, no
remaining pieces of the TSDU
may be received until the cur-
rent 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 end-
point through which data arrives is specified by a file descriptor previously returned by the t_open() function. By default, t_rcv() exe-
cutes 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() func-
tions, 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). delim off
t_rcv(3)