t_listen(NET)
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(NET).
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(S),
intro(NET),
t_accept(NET),
t_bind(NET),
t_connect(NET),
t_open(NET),
t_rcvconnect(NET)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005