Tcl_HandleAlloc,     Tcl_HandleFree,    Tcl_HandleTblInit,
       Tcl_HandleTblRelease,  Tcl_HandleTblUseCount   Tcl_Handle­
       Walk,   Tcl_HandleXlate   -  Dynamic,  handle  addressable
       tables.


SYNOPSIS

       #include <tclExtend.h>

       void_pt
       Tcl_HandleTblInit (const char *handleBase,
                          int         entrySize,
                          int         initEntries);

       int
       Tcl_HandleTblUseCount (void_pt  headerPtr,
                              int      amount);

       void
       Tcl_HandleTblRelease (void_pt headerPtr);

       void_pt
       Tcl_HandleAlloc (void_pt   headerPtr,
                        char     *handlePtr);

       void_pt
       Tcl_HandleXlate (Tcl_Interp *interp,
                        void_pt     headerPtr,
                        const char *handle);

       void_pt
       Tcl_HandleWalk (void_pt   headerPtr,
                       int      *walkKeyPtr);

       void
       Tcl_WalkKeyToHandle (void_pt   headerPtr,
                            int       walkKey,
                            char     *handlePtr);

       void
       Tcl_HandleFree (void_pt headerPtr,
                       void_pt entryPtr);


DESCRIPTION

       The Tcl handle facility provides a  way  to  manage  table
       entries  that  may  be referenced by a textual handle from
       Tcl code.  This is provided for applications that need  to
       create  data structures in one command, return a reference
       (i.e. pointer) to that particular data structure and  then
       access  that  data structure in other commands. An example
       application is file handles.

       A handle consists of a base name, which  is  some  unique,

       appended to the base  name  (e.g.  `file3').   The  handle
       facility  is  designed to provide a standard mechanism for
       building Tcl  commands  that  allocate  and  access  table
       entries  based on an entry index.  The tables are expanded
       when needed, consequently pointers to entries  should  not
       be  kept,  as  they  will become invalid when the table is
       expanded.  If the table entries are large or pointers must
       be  kept  to  the  entries, then the the entries should be
       allocated separately  and  pointers  kept  in  the  handle
       table.   A use count is kept on the table.  This use count
       is intended to determine when a table shared  by  multiple
       commands is to be release.

   Tcl_HandleTblInit
       Create and initialize a Tcl dynamic handle table.  The use
       count on the table is set to one.

       Parameters:
         o handleBase - The base name of the handle,  the  handle
         will  be  returned in the form "baseNN", where NN is the
         table entry number.
         o entrySize - The size of an entry, in bytes.
         o initEntries - Initial size of the table, in entries.

       Returns:
         A pointer to the table header.

   Tcl_HandleTblUseCount
       Alter the handle table use count by the specified  amount,
       which  can be positive or negative.  Amount may be zero to
       retrieve the use count.

       Parameters:
         o headerPtr - Pointer to the table header.
         o amount - The amount to alter the use count by.

       Returns:
         The resulting use count.

   Tcl_HandleTblRelease
       Decrement the use count on a Tcl dynamic handle table.  If
       the  count  goes  to  zero  or  negative, then release the
       table.

       Parameters:
         o headerPtr - Pointer to the table header.

   Tcl_HandleAlloc
       Allocate an entry and associate a handle with it.

       Parameters:
         o headerPtr - A pointer to the table header.
         o handlePtr - Buffer to return handle in. It must be big


       Returns:
         A pointer to the allocated entry (user part).

   Tcl_HandleXlate
       Translate a handle to a entry pointer.

       Parameters:
         o interp - A error message may be returned in result.
         o headerPtr - A pointer to the table header.

         o handle - The handle assigned to the entry.

       Returns:
         A pointer to the entry, or NULL if an error occurred.

   Tcl_HandleWalk
       Walk  through  and  find every allocated entry in a table.
       Entries may be deallocated during a walk, but  should  not
       be allocated.

       Parameters:
         o headerPtr - A pointer to the table header.
         o  walkKeyPtr  -  Pointer  to  a variable to use to keep
         track of the place in the table.  The variable should be
         initialized to -1 before the first call.
       Returns:
         A  pointer to the next allocated entry, or NULL if there
         are not more.

   Tcl_WalkKeyToHandle
       Convert a walk key, as returned from a call to Tcl_Handle­
       Walk  into  a  handle.   The Tcl_HandleWalk must have suc­
       ceeded.

       Parameters:
         o headerPtr - A pointer to the table header.
         o walkKey - The walk key.
         o handlePtr - Buffer to return handle in. It must be big
         enough to hold the name.

   Tcl_HandleFree
       Frees a handle table entry.

       Parameters:
         o headerPtr - A pointer to the table header.
         o entryPtr - Entry to free.


Man(1) output converted with man2html