T_LISTEN(3NSL) Networking Services Library Functions T_LISTEN(3NSL)
NAME
t_listen - listen for a connection indication
SYNOPSIS
#include <xti.h>
int t_listen(
int fd,
struct t_call *call);
DESCRIPTION
This routine is part of the
XTI interfaces which evolved from the
TLI interfaces.
XTI represents the future evolution of these interfaces.
However,
TLI interfaces are supported for compatibility. When using a
TLI routine that has the same name as an
XTI routine, the
tiuser.h header
file must be used. Refer to the
TLI COMPATIBILITY section for a
description of differences between the two interfaces.
This function listens for a connection indication from a calling
transport user. The argument
fd identifies the local transport endpoint
where connection indications arrive, and on return,
call contains
information describing the connection indication. The parameter
call points to a
t_call structure which contains the following members:
struct netbuf addr; struct netbuf opt; struct netbuf udata; int sequence; 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(3NSL).
Note, however that
t_connect(3NSL) may fail for other reasons, for
example
TADDRBUSY.
opt returns options associated with the connection
indication,
udata returns any user data sent by the caller on the
connection request, and
sequence is a number that uniquely identifies the
returned connection indication. The value of
sequence enables the user to
listen for multiple connection 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 the
t_listen() to indicate the maximum size of the buffer for each. If the
maxlen field
of
call->addr,
call->opt or
call->udata is set to zero, no information
is returned for this parameter.
By default,
t_listen() executes in synchronous mode and waits for a
connection indication to arrive before returning to the user. However, if
O_NONBLOCK is set via
t_open(3NSL) or
fcntl(2),
t_listen() executes
asynchronously, reducing to a poll for existing connection indications.
If none are available, it returns -1 and sets
t_errno to
TNODATA.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Otherwise, a value
of -1 is returned and
t_errno is set to indicate an error.
VALID STATES
T_IDLE,
T_INCONERRORS
On failure,
t_errno is 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 referenced by
fd 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 connection
indication information to be returned in
call is
discarded. The value of
sequence returned can be used to
do a
t_snddis(3NSL).
TLOOK An asynchronous event has occurred on this transport
endpoint and requires immediate attention.
TNODATA O_NONBLOCK was set, but no connection indications had been
queued.
TNOTSUPPORT This function is not supported by the underlying transport
provider.
TOUTSTATE The communications endpoint referenced by
fd is not in
one of the states in which a call to this function is
valid.
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 error
(t_errno).
TQFULL The maximum number of outstanding connection indications
has been reached for the endpoint referenced by
fd. Note
that a subsequent call to
t_listen() may block until
another incoming connection indication is available. This
can only occur if at least one of the outstanding
connection indications becomes no longer outstanding, for
example through a call to
t_accept(3NSL).
TSYSERR A system error has occurred during execution of this
function.
TLI COMPATIBILITY
The
XTI and
TLI interface definitions have common names but use different
header files. This, and other semantic differences between the two
interfaces are described in the subsections below.
Interface Header
The
XTI interfaces use the header file,
xti.h.
TLI interfaces should
not use this header. They should use the header:
#include <tiuser.h>
Error Description Values
The
t_errno values
TPROTO, TBADQLEN, and
TQFULL can be set by the
XTI interface but not by the
TLI interface.
A
t_errno value that this routine can return under different
circumstances than its
XTI counterpart is
TBUFOVFLW. It can be returned
even when the
maxlen field of the corresponding buffer has been set to
zero.
Option Buffers
The format of the options in an
opt buffer is dictated by the transport
provider. Unlike the
XTI interface, the
TLI interface does not fix the
buffer format.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT Level | Safe |
+---------------+-----------------+
SEE ALSO
fcntl(2),
t_accept(3NSL),
t_alloc(3NSL),
t_bind(3NSL),
t_connect(3NSL),
t_open(3NSL),
t_optmgmt(3NSL),
t_rcvconnect(3NSL),
t_snddis(3NSL),
attributes(7)WARNINGS
Some transport providers do not differentiate between a connection
indication and the connection itself. If this is the case, a successful
return of
t_listen() indicates an existing connection.
February 18, 2015
T_LISTEN(3NSL)