Content-type: text/html
Man page of t_listen
t_listen
Section: C Library Functions (3)
Index
Return to Main Contents
NAME
t_listen - Listens for a connect request
LIBRARY
XTI Library (libxti.a)
SYNOPSIS
#include <xti.h>
int t_listen(
int fd,
struct t_call *call) ;
STANDARDS
Interfaces documented on this reference page conform to industry
standards as follows:
t_listen: XPG4-UNIX
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.
VALID STATES
The t_listen() function can only be called in the T_IDLE
and T_INCON transport provider states.
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 flag 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.
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.
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 flag 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).
RELATED INFORMATION
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)
delim off
Index
- NAME
-
- LIBRARY
-
- SYNOPSIS
-
- STANDARDS
-
- PARAMETERS
-
- VALID STATES
-
- DESCRIPTION
-
- RETURN VALUE
-
- ERRORS
-
- RELATED INFORMATION
-
This document was created by
man2html,
using the manual pages.
Time: 02:42:00 GMT, October 02, 2010