Content-type: text/html Man page of t_listen

t_listen

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

t_listen - Listens for a connect request  

LIBRARY

XTI Library (libxti.a)  

SYNOPSIS

#include <xti.h>

int t_listen(

  int
fd,
  struct t_call *call) ;
 

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

t_listen: XPG4-UNIX

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_listen() is called:

ParametersBefore CallAfter Call

fdyn
call->addr.maxlenyn
call->addr.lenny
call->addr.bufo(o)
call->opt.maxlenyn
call->opt.lenny
call->opt.bufo(o)
call->udata.maxlenyn
call->udata.lenny
call->udata.bufo(o)
call->sequenceny
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.
(o)  The content of the object pointed to by o is optional.
fd
Specifies a file descriptor returned by the t_open() function that identifies the local transport endpoint where connect indication may arrive.

call
Points to a type t_call structure used to specify information that describes the connect indication. The t_call structure has the following four members:
struct netbuf   addr
Specifies a buffer for protocol address information sent by the calling transport user. The type netbuf structure referenced by this member is defined in the xti.h include file. This structure, which is used to define buffer parameters, has the following members:
unsigned int   maxlen
Specifies the maximum byte length of the data buffer.
unsigned int   len
Specifies the actual byte length of data written to the buffer. char   *buf Points to the buffer location.
struct netbuf   opt
Specifies a buffer for protocol-specific parameters associated with the connect request.
struct netbuf   udata
Specifies a buffer for user data sent by the caller.
int   sequence
Specifies a unique identification number used to identify the returned connect indication.
 
The sequence parameter pointed to by the call parameter is used to uniquely identify the returned connection indication. Values greater than 1 for this parameter enable the transport user to listen for more than a single connect indication before responding to any of those returned.

Because this function returns values for the addr, opt, and udata fields of call, each maxlen parameter must be set before calling this function, to indicate the maximum size of the buffer associated with values sent by the caller.  

VALID STATES

The t_listen() function can only be called in the T_IDLE and T_INCON transport provider states.  

DESCRIPTION

The t_listen() function is an XTI connection-oriented service function that listens for a connect request from a calling transport user. The transport endpoint where the connect indications arrive is specified by a file descriptor previously returned by the t_open() function. By default, the t_listen() function executes in the synchronous operating mode. In the synchronous operating mode, t_listen() waits for a connect indication to arrive before returning control to the transport user who called this function.

When the transport endpoint specified by the fd file descriptor has been opened with the O_NONBLOCK flag set when the t_open() or fcntl() function is called, the t_listen() function executes in asynchronous mode.

When the t_listen() function executes in asynchronous mode, it polls for existing connect indications. If none are available, it returns -1 and sets t_errno to [TNODATA].

The t_listen() function returns a pointer to a type t_call structure, which defines information associated with the arriving connect request. The t_call structure also references a type netbuf structure. Both structures are defined in the xti.h include file.  

RETURN VALUE

Upon successful completion, a value of 0 (zero) is returned. Otherwise, a value of -1 is returned and t_errno is set to indicate the error.  

ERRORS

If the t_listen() function fails, t_errno may be set to one of the following values:

[TBADF]
The specified file descriptor does not refer to a transport endpoint.
[TBADQLEN]
The qlen argument of the endpoint referenced by the fd parameter is zero.
[TBUFOVFLW]
The number of bytes allocated for an incoming argument (maxlen) is greater than 0 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. The value of sequence returned can be used to do a t_snddis().
[TLOOK]
An asynchronous event has occurred on this transport endpoint and requires immediate attention.
[TNODATA]
The 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 function was issued in the wrong sequence on the transport endpoint referenced by the fd parameter.
[TSYSERR]
A system error has occurred during execution of this function.
[TQFULL]
The maximum number of outstanding indications has been reached for the endpoint referenced by fd.
[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_accept(3), t_alloc(3), t_bind(3), t_connect(3), t_open(3), t_optmgmt(3), t_rcvconnect(3), t_snddis(3) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
VALID STATES
DESCRIPTION
RETURN VALUE
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:00 GMT, October 02, 2010