Index Click this button to go to the index for this section.



t_listen - Listens for a connect request


XTI Library (libxti.a)


#include <xti.h> int t_listen( int fd, struct t_call *call) ;


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.


The following table summarizes the relevance of input and output parameters before and after t_listen() is called: Parameters Before Call After Call _____________________________________________ fd y n call->addr.maxlen y n call->addr.len n y call->addr.buf o (o) call->opt.maxlen y n call->opt.len n y call->opt.buf o (o) call->udata.maxlen y n call->udata.len n y call->udata.buf o (o) call->sequence n y 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.


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


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.


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.


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).


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)