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 

       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.  Typ-
                                                      ically  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 associ-
                                                      ation.
                                                      Ignored  if
                                                      NULL.

       ClientData             clientData    (in)      Arbitrary
                                                      one-word
                                                      value asso-
                                                      ciated 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 association.

       Storage management is facilitated  by  storing  with  each
       association  a  procedure  to call when the interpreter is
       deleted. This procedure can dispose of the  storage  occu-
       pied 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 spec-
       ifies the address of a procedure to invoke if  the  inter-
       preter  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 associa-
       tion 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 speci-
       fied key in the given  interpreter.   Then  it  calls  the
       deletion procedure.

KEYWORDS
       association, data, deletion procedure, interpreter, key



Tcl                            7.5            Tcl_SetAssocData(3)