Tcl_GetAssocData(3tcl)

Tcl_SetAssocData(3)  Tcl Library Procedures   Tcl_SetAssocData(3)

_________________________________________________________________

NAME

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

SYNOPSIS

     #include <tcl.h>

     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
                                                     association
                                                     with   which
                                                     to     store
                                                     data or from
                                                     which     to
                                                     delete    or
                                                     retrieve
                                                     data.  Typi-
                                                     cally    the
                                                     module  pre-
                                                     fix   for  a
                                                     package.

     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
                                                     procedure
                                                     for

Tcl                     Last change: 7.5                        1

Tcl_SetAssocData(3)  Tcl Library Procedures   Tcl_SetAssocData(3)

                                                     association.
                                                     Ignored   if
                                                     NULL.

     ClientData clientData (in)                      Arbitrary
                                                     one-word
                                                     value  asso-
                                                     ciated  with
                                                     the    given
                                                     key  in this
                                                     interpreter.
                                                     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                     Last change: 7.5                        2

Tcl_SetAssocData(3)  Tcl Library Procedures   Tcl_SetAssocData(3)

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

Tcl                     Last change: 7.5                        3