Manual Pages for UNIX Operating System command usage for man Tcl_SetAssocData

Tcl Library Procedures                     Tcl_SetAssocData(3TCL)



_________________________________________________________________

NAME
     Tcl_GetAssocData,  Tcl_SetAssocData,  Tcl_DeleteAssocData  -
     manage  associations  of string keys and user specified data
     with Tcl interpreters.

SYNOPSIS
     #include 

     ClientData
     Tcl_GetAssocData(interp, key, delProcPtr)

     Tcl_SetAssocData(interp, key, delProc, clientData)

     Tcl_DeleteAssocData(interp, key)

ARGUMENTS
     Tcl_Interp             *interp       (in)      Interpreter
                                                    in  which  to
                                                    execute   the
                                                    specified
                                                    command.       |

     CONST char             *key          (in)                          ||
                                                    Key for asso-
                                                    ciation  with
                                                    which      to
                                                    store data or
                                                    from which to
                                                    delete     or
                                                    retrieve
                                                    data.   Typi-
                                                    cally     the
                                                    module prefix
                                                    for  a  pack-
                                                    age.

     Tcl_InterpDeleteProc   *delProc      (in)      Procedure  to
                                                    call     when
                                                    interp     is
                                                    deleted.

     Tcl_InterpDeleteProc   **delProcPtr  (in)      Pointer    to
                                                    location   in
                                                    which      to
                                                    store address
                                                    of    current
                                                    deletion pro-
                                                    cedure    for
                                                    association.
                                                    Ignored    if



Tcl                     Last change: 7.5                        1






Tcl Library Procedures                     Tcl_SetAssocData(3TCL)



                                                    NULL.

     ClientData             clientData    (in)      Arbitrary
                                                    one-word
                                                    value associ-
                                                    ated with the
                                                    given key  in
                                                    this   inter-
                                                    preter.  This
                                                    data is owned
                                                    by        the
                                                    caller.
_________________________________________________________________


DESCRIPTION
     These procedures allow extensions  to  associate  their  own
     data  with  a Tcl interpreter.  An association consists of a
     string key, typically the name of the extension, and a  one-
     word value, which is typically a pointer to a data structure
     holding data  specific  to  the  extension.   Tcl  makes  no
     interpretation of either the key or the value for an associ-
     ation.

     Storage management is facilitated by storing with each asso-
     ciation a procedure to call when the interpreter is deleted.
     This procedure can dispose of the storage  occupied  by  the
     client's data in any way it sees fit.

     Tcl_SetAssocData creates an association between a string key
     and  a  user  specified  datum in the given interpreter.  If
     there  is  already  an  association  with  the  given   key,
     Tcl_SetAssocData overwrites it with the new information.  It
     is up to callers to organize their use  of  names  to  avoid
     conflicts,  for example, by using package names as the keys.
     If the deleteProc argument  is  non-NULL  it  specifies  the
     address  of  a  procedure  to  invoke  if the interpreter is
     deleted  before  the  association  is  deleted.   DeleteProc
     should  have  arguments  and  result  that  match  the  type
     Tcl_InterpDeleteProc:
          typedef void Tcl_InterpDeleteProc(
            ClientData clientData,
            Tcl_Interp *interp);
     When deleteProc is invoked the clientData and  interp  argu-
     ments will be the same as the corresponding arguments passed
     to Tcl_SetAssocData.  The deletion  procedure  will  not  be
     invoked if the association is deleted before the interpreter
     is deleted.

     Tcl_GetAssocData returns the datum stored in the association
     with  the specified key in the given interpreter, and if the
     delProcPtr field is non-NULL, the address  indicated  by  it



Tcl                     Last change: 7.5                        2






Tcl Library Procedures                     Tcl_SetAssocData(3TCL)



     gets  the  address  of the delete procedure stored with this
     association. If no association with the specified key exists
     in the given interpreter Tcl_GetAssocData returns NULL.

     Tcl_DeleteAssocData deletes an association with a  specified
     key  in  the  given interpreter.  Then it calls the deletion
     procedure.

KEYWORDS
     association, data, deletion procedure, interpreter, key

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

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.






























Tcl                     Last change: 7.5                        3