1 | '\" |
---|
2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: AssocData.3,v 1.7 2004/10/07 15:15:35 dkf Exp $ |
---|
9 | .so man.macros |
---|
10 | .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures" |
---|
11 | .BS |
---|
12 | .SH NAME |
---|
13 | Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations of string keys and user specified data with Tcl interpreters |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h>\fR |
---|
17 | .sp |
---|
18 | ClientData |
---|
19 | \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR) |
---|
20 | .sp |
---|
21 | \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR) |
---|
22 | .sp |
---|
23 | \fBTcl_DeleteAssocData\fR(\fIinterp, key\fR) |
---|
24 | .SH ARGUMENTS |
---|
25 | .AS Tcl_InterpDeleteProc **delProcPtr |
---|
26 | .AP Tcl_Interp *interp in |
---|
27 | Interpreter in which to execute the specified command. |
---|
28 | .AP "const char" *key in |
---|
29 | Key for association with which to store data or from which to delete or |
---|
30 | retrieve data. Typically the module prefix for a package. |
---|
31 | .AP Tcl_InterpDeleteProc *delProc in |
---|
32 | Procedure to call when \fIinterp\fR is deleted. |
---|
33 | .AP Tcl_InterpDeleteProc **delProcPtr in |
---|
34 | Pointer to location in which to store address of current deletion procedure |
---|
35 | for association. Ignored if NULL. |
---|
36 | .AP ClientData clientData in |
---|
37 | Arbitrary one-word value associated with the given key in this |
---|
38 | interpreter. This data is owned by the caller. |
---|
39 | .BE |
---|
40 | |
---|
41 | .SH DESCRIPTION |
---|
42 | .PP |
---|
43 | These procedures allow extensions to associate their own data with |
---|
44 | a Tcl interpreter. |
---|
45 | An association consists of a string key, typically the name of |
---|
46 | the extension, and a one-word value, which is typically a pointer |
---|
47 | to a data structure holding data specific to the extension. |
---|
48 | Tcl makes no interpretation of either the key or the value for |
---|
49 | an association. |
---|
50 | .PP |
---|
51 | Storage management is facilitated by storing with each association a |
---|
52 | procedure to call when the interpreter is deleted. This |
---|
53 | procedure can dispose of the storage occupied by the client's data in any |
---|
54 | way it sees fit. |
---|
55 | .PP |
---|
56 | \fBTcl_SetAssocData\fR creates an association between a string |
---|
57 | key and a user specified datum in the given interpreter. |
---|
58 | If there is already an association with the given \fIkey\fR, |
---|
59 | \fBTcl_SetAssocData\fR overwrites it with the new information. |
---|
60 | It is up to callers to organize their use of names to avoid conflicts, |
---|
61 | for example, by using package names as the keys. |
---|
62 | If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a |
---|
63 | procedure to invoke if the interpreter is deleted before the association |
---|
64 | is deleted. \fIDeleteProc\fR should have arguments and result that match |
---|
65 | the type \fBTcl_InterpDeleteProc\fR: |
---|
66 | .CS |
---|
67 | typedef void Tcl_InterpDeleteProc( |
---|
68 | ClientData \fIclientData\fR, |
---|
69 | Tcl_Interp *\fIinterp\fR); |
---|
70 | .CE |
---|
71 | When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR |
---|
72 | arguments will be the same as the corresponding arguments passed to |
---|
73 | \fBTcl_SetAssocData\fR. |
---|
74 | The deletion procedure will \fInot\fR be invoked if the association |
---|
75 | is deleted before the interpreter is deleted. |
---|
76 | .PP |
---|
77 | \fBTcl_GetAssocData\fR returns the datum stored in the association with the |
---|
78 | specified key in the given interpreter, and if the \fIdelProcPtr\fR field |
---|
79 | is non-\fBNULL\fR, the address indicated by it gets the address of the |
---|
80 | delete procedure stored with this association. If no association with the |
---|
81 | specified key exists in the given interpreter \fBTcl_GetAssocData\fR |
---|
82 | returns \fBNULL\fR. |
---|
83 | .PP |
---|
84 | \fBTcl_DeleteAssocData\fR deletes an association with a specified key in |
---|
85 | the given interpreter. Then it calls the deletion procedure. |
---|
86 | .SH KEYWORDS |
---|
87 | association, data, deletion procedure, interpreter, key |
---|