t_rcv Subroutine for Transport Layer Interface

Communications Technical Reference, Volume 2

t_rcv Subroutine for Transport Layer Interface

Purpose

Receives normal data or expedited data sent over a connection.

Library

Transport Layer Interface Library (libtli.a)

Syntax

int t_rcv(fd, buf, nbytes, flags)
int fd;
char *buf;
unsigned nbytes;
int *flags;

Description

The t_rcv subroutine receives either normal or expedited data. By default, the t_rcv subroutine operates in synchronous mode and will wait for data to arrive if none is currently available. However, if the O_NDELAY flag is set (using the t_open subroutine or the fcntl command), the t_rcv subroutine runs in asynchronous mode and will stop if no data is available.

On return from the call, if the T_MORE flag is set in the flags parameter, this indicates that there is more data. This means that the current transport service data unit (TSDU) or expedited transport service data unit (ETSDU) must be received in multiple t_rcv subroutine calls. Each t_rcv subroutine with the T_MORE flag set indicates that another t_rcv subroutine must follow immediately to get more data for the current TSDU. The end of the TSDU is identified by the return of a t_rcv subroutine call with the T_MORE flag not set. If the transport provider does not support the concept of a TSDU as indicated in the info parameter on return from a t_open or t_getinfo subroutine, the T_MORE flag is not meaningful and should be ignored.

On return, the data returned is expedited data if the T_EXPEDITED flag is set in the flags parameter. If the number of bytes of expedited data exceeds the value in the nbytes parameter, the t_rcv subroutine will set the T_EXPEDITED and T_MORE flags on return from the initial call. Subsequent calls to retrieve the remaining ETSDU not have the T_EXPEDITED flag set on return. The end of the ETSDU is identified by the return of a t_rcv subroutine call with the T_MORE flag not set.

If expedited data arrives after part of a TSDU has been retrieved, receipt of the remainder of the TSDU will be suspended until the ETSDU has been processed. Only after the full ETSDU has been retrieved (the T_MORE flag is not set) will the remainder of the TSDU be available to the user.

Parameters

fd	Identifies the local transport end point through which data will arrive.
buf	Points to a receive buffer where user data will be placed.
nbytes	Specifies the size of the receiving buffer.
flags	Specifies optional flags.

Return Values

On successful completion, the t_rcv subroutine returns the number of bytes it received. Otherwise, it returns a value of -1 and sets the t_errno variable to indicate the error.

Error Codes

If unsuccessful, the t_errno variable may be set to one of the following:

TBADF	The specified file descriptor does not refer to a transport end point.
TLOOK	An asynchronous event has occurred on this transport end point and requires immediate attention.
TNODATA	The O_NDELAY flag was set, but no data is currently available from the transport provider.
TNOTSUPPORT	This subroutine is not supported by the underlying transport provider.
TOUTSTATE	The subroutine was issued in the wrong sequence.
TSYSERR	A system error has occurred during operation of this subroutine.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The t_getinfo subroutine, t_look subroutine, t_open subroutine, t_snd subroutine.

List of Streams Programming References and STREAMS Overview in AIX Version 4.3 Communications Programming Concepts.