t_rcv Subroutine for X/Open Transport Interface

AIX Version 4.3 Communications Technical Reference, Volume 2

t_rcv Subroutine for X/Open Transport Interface

Purpose

Receive data or expedited data sent over a connection.

Library

X/Open Transport Interface Library (libxti.a)

Syntax

#include <xti.h>

int t_rcv (
    int fd,
    void *buf,
    unsigned int 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 waits for data to arrive if none is currently available. However, if O_NONBLOCK is set via the t_open subroutine or the fcntl parameter, the, t_rcv subroutine executes in asynchronous mode and fails if no data is available. (See the TNODATA error in "Error Codes" below.)

Parameters

Identifies the local transport endpoint through which data will arrive.

buf

Points to a receive buffer where user data will be placed.

nbytes

Specifies the size of the receive buffer.

flags

Specifies optional flags. This parameter may be set on return from the t_rcv subroutine. The possible values are:

T_MORE

If set, on return from the call, indicates that there is more data, and the current transport service data unit (TSDU) or expedited transport service data unit (ETSDU) must be received in multiple t_rcv calls. In the asynchronous mode, the T_MORE flag may be set on return from the t_rcv call even when the number of bytes received is less than the size of the receive buffer specified. Each t_rcv call with the T_MORE flag set, indicates that another t_rcv call must follow to get more data for the current TSDU. The end of the TSDU is identified by the return of a t_rcv 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 the t_open or t_getinfo subroutines, the T_MORE flag is not meaningful and should be ignored. If the nbytes parameter is greater than zero on the call to t_rcv, t_rcv returns 0 only if the end of a TSDU is being returned to the user.

T_EXPEDITED

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

In synchronous mode, the only way to notify the user of the arrival of normal or expedited data is to issue this subroutine or check for the T_DATA or T_EXDATA events using the t_look subroutine. Additionally, the process can arrange to be notified via the Event Management interface.

Valid States

T_DATAXFER, T_OUTREL.

Return Values

On successful completion, the t_rcv subroutine returns the number of bytes received. Otherwise, it returns -1 on failure and t_errno is set to indicate the error.

Error Codes

On failure, t_errno is set to one of the following:

TBADF	The specified file descriptor does not refer to a transport endpoint.
TLOOK	An asynchronous event has occurred on this transport endpoint and requires immediate attention.
TNODATA	O_NONBLOCK 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 on the transport endpoint referenced by the fd parameter.
TPROTO	This error indicates that a communication problem has been detected between the X/Open Transport Interface and the transport provider for which there is no other suitable X/Open Transport Interface (t_errno).
TSYSERR	A system error has occurred during execution of this subroutine.

Related Information

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