 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
t_listen(3)
NAME
t_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 standards
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 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.
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
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 option 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).
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|