NAME [Toc] [Back]
t_listen() - listen for a connect request
SYNOPSIS [Toc] [Back]
#include <xti.h> /* for X/OPEN Transport Interface - XTI */
/* or */
#include <tiuser.h> /* for Transport Layer Interface - TLI */
int t_listen (fd, call);
struct t_call *call;
DESCRIPTION [Toc] [Back]
The t_listen() function listens for a connect request from a calling
transport user. fd identifies the local transport endpoint where
connect indications arrive. On return, call contains information
describing the connect indication. The parameter call points to a
t_call structure which contains the following members:
struct netbuf addr;
struct netbuf opt;
struct netbuf udata;
The type netbuf structure is defined in the <xti.h> or <tiuser.h>
header file. This structure, which is used to define buffer
parameters, has the following members:
unsigned int maxlen maximum byte length of the data buffer
unsigned int len actual byte length of data written to
char *buf points to buffer location
In call, addr returns the protocol address of the calling transport
user. This address is in a format usable in future calls to
t_connect(). Note, however that t_connect() may fail for other
reasons, for example [TADDRBUSY].
opt returns protocol-specific parameters associated with the connect
request. For XTI over the OSI transport provider, struct
isoco_options should be used. For TLI, see the documentation for the
transport provider being used.
udata returns any user data sent by the caller on the connect request.
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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
Since this function returns values for the addr, opt, and udata fields
of call, the maxlen field of each must be set before issuing the
t_listen to indicate the maximum size of the buffer for each.
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].
Thread-Safeness [Toc] [Back]
The t_listen() function is safe to be called by multithreaded
applications, and it is thread-safe for both POSIX Threads and DCE
User Threads. It has a cancellation point. It is neither asynccancel
safe nor async-signal safe. Finally, it is not fork-safe.
Valid States [Toc] [Back]
Caveats [Toc] [Back]
Some transport providers do not differentiate between a connect
indication and the connection itself. If this is the case, a
successful return of t_listen() indicates an existing connection (see
Appendix B, "Internet Protocol-specific Information," of the CAE
Specification X/Open Transport Interface (XTI) manual).
RETURN VALUE [Toc] [Back]
Upon successful completion, a value of 0 is returned Otherwise, a
value of -1 it returned and t_errno is set to indicate the error.
ERRORS [Toc] [Back]
On failure, t_errno is set to the following:
[TBADF] The specified identifier does not refer to a
[TBADQLEN] The argument qlen of the endpoint referenced by fd is
[TBUFOVFLW] The number of bytes allocated for an incoming
argument (maxlen) 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 call is
discarded. For XTI only, the value of sequence
returned can be used to do a t_snddis().
[TNODATA] O_NONBLOCK was set, but no connect indication has
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
[TLOOK] An asynchronous event has occurred on this transport
endpoint and requires immediate attention.
[TOUTSTATE] This function was issued in the wrong sequence on the
transport endpoint referenced by fd.
[TSYSERR] A system error has occurred during execution of this
[TQFULL] The maximum number of outstanding indications has
been reached for the endpoint referenced by fd.
[TPROTO] (XTI only) This error indicates that a communication
problem has been detected between XTI and the
transport provider for which there is no suitable XTI
FILES [Toc] [Back]
/usr/include/xti.h XTI data structures
/usr/include/tiuser.h TLI data structures
SEE ALSO [Toc] [Back]
fcntl(2), t_accept(3), t_alloc(3), t_bind(3), t_connect(3), t_open(3),
STANDARDS CONFORMANCE [Toc] [Back]
t_listen(): SVID2, XPG3, XPG4
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003 [ Back ]