t_listen(3xti)

t_listen -- listen for a connect indication

Synopsis

cc [options] file -lnsl

#include <xti.h>

int t_listen(int fd, struct t_call call);

Description

This function is a TLI/XTI routine for use in establishing a transport connection. t_listen listens for a connect indication from another transport user and is designed for use by server applications using connection-mode transport services.

fd identifies the local transport endpoint where connect indications arrive, and on return, call contains information describing the connect indication.

Parameters

fd: the file descriptor for the transport endpoint where connect indications arrive.
call: points to the t_call structure used to describe the connect indications.

Structure definitions

call points to a t_call structure, which contains the following members:

   struct netbuf addr;     /* address             */
   struct netbuf opt;      /* options             */
   struct netbuf udata;    /* user data           */
   int sequence;           /* sequence number     */

netbuf is described in intro(3xti). In call, addr returns the protocol address of the other transport user, opt returns protocol-specific parameters associated with the connect indication, udata returns any user data sent by the other user on the connect request, and sequence is a number that 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 this function returns values for the addr, opt, and udata fields of call, the maxlen field of each must be set before issuing t_listen to indicate the maximum size of the buffer for each.

State transitions

T_IDLE on entry. T_INCON (successful) or T_IDLE (no requests) on exit.

Files

/usr/lib/libxti.so: X/Open^® Transport Interface Library (shared object)
/usr/lib/libnsl.so: Network Services Library (shared object)

Usage

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

If the transport provider does not distinguish between a connect indication and an actual connection, the return of t_listen indicates a connection. If a user issues t_listen in synchronous mode on a transport endpoint that was not bound for listening (that is, qlen was zero on t_bind), the call will wait forever because no connect indications will arrive on that endpoint.

Return values

t_listen returns 0 on success and -1 on failure and t_errno is set to indicate the error.

Errors

On failure, t_errno may be set to one of the following:

TBADF: The specified file descriptor does not refer to a transport endpoint.
TBADQLEN: The argument qlen of the endpoint specified by fd is 0.
TBUFOVFLW: The number of bytes (maxlen) allocated for an incoming argument is greater than zero but 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 call is discarded.
TNODATA: O_NONBLOCK was set, but no connect indications had been queued.
TLOOK: An asynchronous event has occurred on this transport endpoint and requires immediate attention.
TNOTSUPPORT: This function is not supported by the underlying transport provider.
TSYSERR: A system error has occurred during execution of this function.
TQFULL: The maximum number of connect indications has been reached for the endpoint specified by fd.
TOUTSTATE: The function was issued in the wrong sequence on the transport endpoint referenced by fd.
TPROTO: A communication problem has been detected with the transport provider and there is no other value of t_errno to describe the error condition.

References

fcntl(2), intro(3xti), t_accept(3xti), t_bind(3xti), t_connect(3xti), t_open(3xti), t_rcvconnect(3xti)