Manual Pages for UNIX Operating System command usage for man t_listen

Networking Services Library Functions              t_listen(3NSL)



NAME
     t_listen - listen for a connection indication

SYNOPSIS
     #include 

     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 connec-
     tion 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 con-
     nection 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.




SunOS 5.11           Last change: 7 May 1998                    1






Networking Services Library Functions              t_listen(3NSL)



     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.   Oth-
     erwise,  a  value  of  -1  is returned and t_errno is set to
     indicate an error.

VALID STATES
     T_IDLE, T_INCON

ERRORS
     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  argu-
                    ment.  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 indica-
                    tions had been queued.


     TNOTSUPPORT    This function is not supported by the  under-
                    lying 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.



SunOS 5.11           Last change: 7 May 1998                    2






Networking Services Library Functions              t_listen(3NSL)



     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 incom-
                    ing connection indication is available.  This
                    can  only  occur  if at least one of the out-
                    standing 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 differ-
     ences between the two interfaces are described in  the  sub-
     sections below.

  Interface Header
     The XTI interfaces use the header file,  xti.h.  TLI  inter-
     faces  should  not  use  this  header.   They should use the
     header:

       #include 


  Error Description Values
     The t_errno values TPROT0, 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




SunOS 5.11           Last change: 7 May 1998                    3






Networking Services Library Functions              t_listen(3NSL)



     See attributes(5)  for descriptions of the following  attri-
     butes:



     ____________________________________________________________
    |       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(5)

WARNINGS
     Some transport providers do not differentiate between a con-
     nection indication and the connection itself. If this is the
     case, a successful return of t_listen() indicates an  exist-
     ing connection.

































SunOS 5.11           Last change: 7 May 1998                    4