Technical Reference: Communications, Volume 2

t_listen Subroutine for Transport Layer Interface

Library

Transport Layer Interface Library (libtli.a)

Syntax

#include <tiuser.h>

int t_listen(fd, call) int fd; struct t_call * call;

Description

The t_listen subroutine listens for a connect request from a calling transport user.

Note: If a user issues a t_listen subroutine call in synchronous mode on a transport end point that was not bound for listening (that is, the qlen field was 0 on the t_bind subroutine), the call will never return because no connect indications will arrive on that endpoint.

Parameters

fd Identifies the local transport endpoint where connect indications arrive.

call

Contains information describing the connect indication.

The call parameter points to a t_call structure that contains the following members:

struct netbuf addr;
struct netbuf opt;
struct netbuf udata;
int sequence;

The netbuf structure contains the following fields:

addr: Returns the protocol address of the calling transport user.
opt: Returns protocol-specific parameters associated with the connect request.
udata: Returns any user data sent by the caller on the connect request.
sequence: Uniquely identifies the returned connect indication. The value of sequence enables the user to listen for multiple connect indications before responding to any of them.

Since the t_listen subroutine returns values for the addr,opt, and udata fields of the call parameter, the maxlen field of each must be set before issuing the t_listen subroutine to indicate the maximum size of the buffer for each.

By default, the t_listen subroutine executes in synchronous mode and waits for a connect indication to arrive before returning to the user. However, if the O_NDELAY or O_NONBLOCK flag is set (using the t_open subroutine or the fcntl command), the t_listen subroutine executes asynchronously, reducing to a poll for existing connect indications. If none are available, the t_listen subroutine returns -1 and sets the t_errno variable to TNODATA.

Return Values

On successful completion, the t_listen subroutine returns a value of 0. Otherwise, it returns a value of -1, and the t_errno variable is set to indicate the error.

Error Codes

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

TBADF	The specified file descriptor does not refer to a transport end point.
TBADQLEN	The transport end point is not bound for listening. The qlen is zero.
TBUFOVFLW	The number of bytes allocated for an incoming argument is not sufficient to store the value of that argument. The provider's state, as seen by the user, changes to T_INCON, and the connect-indication information to be returned in the call parameter is discarded.
TLOOK	An asynchronous event has occurred on this transport end point and requires immediate attention.
TNODATA	The O_NDELAY or O_NONBLOCK flag was set, but no connect indications had been queued.
TNOTSUPPORT	This function is not supported by the underlying transport provider.
TOUTSTATE	The subroutine was issued in the wrong sequence.
TSYSERR	A system error has occurred during execution of this function.

Implementation Specifics

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

Related Information

The t_accept subroutine, t_alloc subroutine, t_bind subroutine, t_connect subroutine, t_open subroutine, t_rcvconnect subroutine.

List of Streams Programming References and STREAMS Overview in AIX 5L Version 5.1 Communications Programming Concepts.