t_listen(3)                                                     t_listen(3)




 NAME    [Toc]    [Back]
      t_listen() - listen for a connect request

 SYNOPSIS    [Toc]    [Back]
      #include <xti.h>            /* for X/OPEN Transport Interface - XTI */
      /* or */
      #include <tiuser.h>         /* for Transport Layer Interface - TLI  */

      int t_listen (fd, call);
      int fd;
      struct t_call *call;

 DESCRIPTION    [Toc]    [Back]
      The t_listen() function listens for a connect request from a calling
      transport user.  fd identifies the local transport endpoint where
      connect indications arrive.  On return, call contains information
      describing the connect 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;

      The type netbuf structure is defined in the <xti.h> or <tiuser.h>
      header file.  This structure, which is used to define buffer
      parameters, has the following members:

      unsigned int maxlen           maximum byte length of the data buffer

      unsigned int len              actual byte length of data written to
                                    buffer

      char *buf                     points to buffer location

      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().  Note, however that t_connect() may fail for other
      reasons, for example [TADDRBUSY].

      opt returns protocol-specific parameters associated with the connect
      request.  For XTI over the OSI transport provider, struct
      isoco_options should be used.  For TLI, see the documentation for the
      transport provider being used.

      udata returns any user data sent by the caller on the connect request.

      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.




 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 t_listen(3)                                                     t_listen(3)




      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.

      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].

    Thread-Safeness    [Toc]    [Back]
      The t_listen() function is safe to be called by multithreaded
      applications, and it is thread-safe for both POSIX Threads and DCE
      User Threads.  It has a cancellation point.  It is neither asynccancel
 safe nor async-signal safe.  Finally, it is not fork-safe.

    Valid States    [Toc]    [Back]
      T_IDLE, T_INCON

    Caveats    [Toc]    [Back]
      Some transport providers do not differentiate between a connect
      indication and the connection itself.  If this is the case, a
      successful return of t_listen() indicates an existing connection (see
      Appendix B, "Internet Protocol-specific Information," of the CAE
      Specification X/Open Transport Interface (XTI) manual).

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, a value of 0 is returned  Otherwise, a
      value of -1 it returned and t_errno is set to indicate the error.

 ERRORS    [Toc]    [Back]
      On failure, t_errno is set to the following:

      [TBADF]          The specified identifier 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 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.  For XTI only, the value of sequence
                       returned can be used to do a t_snddis().

      [TNODATA]        O_NONBLOCK was set, but no connect indication has
                       been queued.





 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 t_listen(3)                                                     t_listen(3)




      [TLOOK]          An asynchronous event has occurred on this transport
                       endpoint and requires immediate attention.

      [TOUTSTATE]      This function was issued in the wrong sequence on the
                       transport endpoint referenced by fd.

      [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]         (XTI only) This error indicates that a communication
                       problem has been detected between XTI and the
                       transport provider for which there is no suitable XTI
                       (t_errno).

 FILES    [Toc]    [Back]
      /usr/include/xti.h                 XTI data structures

      /usr/include/tiuser.h              TLI data structures

 SEE ALSO    [Toc]    [Back]
      fcntl(2), t_accept(3), t_alloc(3), t_bind(3), t_connect(3), t_open(3),
      t_snddis(3), t_rcvconnect(3).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      t_listen(): SVID2, XPG3, XPG4


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003