1Tcl_SetAssocData(3)         Tcl Library Procedures         Tcl_SetAssocData(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_GetAssocData,  Tcl_SetAssocData, Tcl_DeleteAssocData - manage asso‐
9       ciations of string keys and user specified data with Tcl interpreters
10

SYNOPSIS

12       #include <tcl.h>
13
14       ClientData
15       Tcl_GetAssocData(interp, key, delProcPtr)
16
17       Tcl_SetAssocData(interp, key, delProc, clientData)
18
19       Tcl_DeleteAssocData(interp, key)
20

ARGUMENTS

22       Tcl_Interp *interp (in)                         Interpreter in which to
23                                                       execute  the  specified
24                                                       command.
25
26       const char *key (in)                            Key   for   association
27                                                       with   which  to  store
28                                                       data or from  which  to
29                                                       delete    or   retrieve
30                                                       data.   Typically   the
31                                                       module   prefix  for  a
32                                                       package.
33
34       Tcl_InterpDeleteProc *delProc (in)              Procedure to call  when
35                                                       interp is deleted.
36
37       Tcl_InterpDeleteProc **delProcPtr (in)          Pointer  to location in
38                                                       which to store  address
39                                                       of   current   deletion
40                                                       procedure for  associa‐
41                                                       tion.  Ignored if NULL.
42
43       ClientData clientData (in)                      Arbitrary      one-word
44                                                       value  associated  with
45                                                       the  given  key in this
46                                                       interpreter.  This data
47                                                       is owned by the caller.
48______________________________________________________________________________
49
50

DESCRIPTION

52       These  procedures  allow  extensions to associate their own data with a
53       Tcl interpreter.  An association consists of a  string  key,  typically
54       the  name  of the extension, and a one-word value, which is typically a
55       pointer to a data structure holding data  specific  to  the  extension.
56       Tcl makes no interpretation of either the key or the value for an asso‐
57       ciation.
58
59       Storage management is facilitated by storing with  each  association  a
60       procedure  to  call when the interpreter is deleted. This procedure can
61       dispose of the storage occupied by the client's data in any way it sees
62       fit.
63
64       Tcl_SetAssocData creates an association between a string key and a user
65       specified datum in the given interpreter.  If there is already an asso‐
66       ciation with the given key, Tcl_SetAssocData overwrites it with the new
67       information.  It is up to callers to organize their  use  of  names  to
68       avoid  conflicts,  for example, by using package names as the keys.  If
69       the deleteProc argument is non-NULL it specifies the address of a  pro‐
70       cedure  to  invoke if the interpreter is deleted before the association
71       is deleted.  DeleteProc should have arguments and result that match the
72       type Tcl_InterpDeleteProc:
73
74              typedef void Tcl_InterpDeleteProc(
75                      ClientData clientData,
76                      Tcl_Interp *interp);
77
78       When  deleteProc is invoked the clientData and interp arguments will be
79       the same as the corresponding  arguments  passed  to  Tcl_SetAssocData.
80       The  deletion  procedure  will  not  be  invoked  if the association is
81       deleted before the interpreter is deleted.
82
83       Tcl_GetAssocData returns the datum stored in the association  with  the
84       specified  key in the given interpreter, and if the delProcPtr field is
85       non-NULL, the address indicated by it gets the address  of  the  delete
86       procedure  stored  with  this  association.  If no association with the
87       specified key exists in the given interpreter Tcl_GetAssocData  returns
88       NULL.
89
90       Tcl_DeleteAssocData  deletes an association with a specified key in the
91       given interpreter.  Then it calls the deletion procedure.
92

KEYWORDS

94       association, data, deletion procedure, interpreter, key
95
96
97
98Tcl                                   7.5                  Tcl_SetAssocData(3)
Impressum