t_alloc(3)                                                       t_alloc(3)




 NAME    [Toc]    [Back]
      t_alloc() - allocate a library structure

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

      char *t_alloc (fd, struct_type, fields);
      int fd;
      int struct_type;
      int fields;

 DESCRIPTION    [Toc]    [Back]
      The t_alloc() function dynamically allocates memory for the various
      transport function argument structures as specified below.  This
      function will allocate memory for the specified structure and will
      also allocate memory for buffers referenced by the structure.

      The structure to allocate is specified by struct_type and must be one
      of the following:

           T_BIND       struct   t_bind
           T_CALL       struct   t_call
           T_OPTMGMT    struct   t_optmgmt
           T_DIS        struct   t_discon
           T_UNITDATA   struct   t_unitdata
           T_UDERROR    struct   t_uderr
           T_INFO       struct   t_info

      where each of these structures may subsequently be used as an argument
      to one or more transport functions.

      Each of the above structures, except T_INFO, contains at least one
      field of type struct netbuf.  For each field of this type, the user
      may specify that the buffer for that field should be allocated as
      well.  The length of the buffer allocated will be equal to or greater
      than the appropriate size returned in the info argument of t_open() or
      t_getinfo().  The relevant fields of the info argument are described
      in the following list.  The fields argument specifies which buffer to
      allocate, where the argument is the bitwise-OR of any of the
      following:

      T_ADDR              The addr field of the t_bind, t_call, t_unitdata,
                          or t_uderr structures.

      T_OPT               The opt field of the t_optmgmt, t_call,
                          t_unitdata, or t_uderr structures.

      T_UDATA             The udata field of the t_call, t_discon, or
                          t_unitdata structures.



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






 t_alloc(3)                                                       t_alloc(3)




      T_ALL               All relevant fields of the given structure.
                          Fields which are not supported by e transport
                          provider specified by fd will not be allocated
                          (info values are <= 0).

      For each field specified in fields, t_alloc() will allocate memory for
      the buffer associated with the field, and initialize the len field to
      zero and the buf pointer and maxlen field accordingly.  Since the
      length of the buffer allocated will be based on the same size
      information that is returned to the user on t_open() or t_getinfo(),
      fd must refer to the transport endpoint through which the newly
      allocated structure will be passed.  In this way the appropriate size
      information can be accessed.  If the size value associated with any
      specified field is -1 or -2 ( see t_open(3) or t_getinfo(3)),
      t_alloc() will be unable to determine the size of the buffer to
      allocate and will fail, setting t_errno to [TSYSERR] and errno to
      [EINVAL].  For any field not specified in fields, buf will be set to a
      null pointer and maxlen will be set to zero.

      Use of t_alloc() to allocate structures will help ensure the
      compatibility of user programs with future releases of the transport
      interface functions.

    Thread-Safeness    [Toc]    [Back]
      The t_alloc() 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]
      All - apart from T_UNINIT

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, t_alloc() returns a pointer to the newly
      allocated structure.  On failure, a null pointer is returned.

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

      [TBADF]             fd The specified endpoint identifier does not
                          refer to a transport endpoint

      [TSYSERR]           A system error has occurred during execution of
                          this function.

      [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).





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






 t_alloc(3)                                                       t_alloc(3)




      [TNOSTRUCTYPE]      Unsupported struct_type requested.  This can
                          include a request for a structure type which is
                          inconsistent with the transport provider type
                          specified, that is, connection-oriented or
                          connectionless.

 SEE ALSO    [Toc]    [Back]
      t_free(3), t_getinfo(3), t_open(3).

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


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