t_listen(3)t_listen(3)NAMEt_listen - Listen for a connect request
SYNOPSIS
#include <xti.h>
int t_listen(
int fd,
struct t_call *call );
LIBRARY
XTI Library (libxti.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
t_listen(): XNS4.0, XNS5.0
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 param‐
eters 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 This is a meaningful parameter. This is not a meaning‐
ful parameter. The content of the object pointed to by y is meaning‐
ful. The content of the object pointed to by o is optional. Specifies
a file descriptor returned by the t_open() function that identifies the
local transport endpoint where connect indication may arrive. 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: 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:
Specifies the maximum byte length of the data buffer. Specifies the
actual byte length of data written to the buffer. Points to the buffer
location. Specifies a buffer for protocol-specific parameters associ‐
ated with the connect request. Specifies a buffer for user data sent
by the caller. Specifies a unique identification number used to iden‐
tify 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.
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 option 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.
ERRORS
If the t_listen() function fails, t_errno may be set to one of the fol‐
lowing values: The specified file descriptor does not refer to a trans‐
port endpoint. The qlen argument of the endpoint referenced by the fd
parameter is zero. The number of bytes allocated for an incoming argu‐
ment (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(). An asynchronous event has occurred on this transport end‐
point and requires immediate attention. The O_NONBLOCK option was set,
but no connect indications had been queued. This function is not sup‐
ported by the underlying transport provider. The function was issued
in the wrong sequence on the transport endpoint referenced by the fd
parameter. A system error has occurred during execution of this func‐
tion. The maximum number of outstanding indications has been reached
for the endpoint referenced by fd. This error indicates that a commu‐
nication problem has been detected between XTI and the transport
provider for which there is no other suitable XTI(t_errno).
VALID STATES
The t_listen function can only be called in the T_IDLE and T_INCON
transport provider states.
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.
SEE ALSO
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)
Standards: standards(5)
Network Programmer's Guide
t_listen(3)
