1 | '\" |
---|
2 | '\" Copyright (c) 2002 Donal K. Fellows |
---|
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 | '\" CVS: @(#) $Id: TraceCmd.3,v 1.11 2007/12/13 15:22:32 dgp Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" |
---|
11 | .BS |
---|
12 | .SH NAME |
---|
13 | Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h>\fR |
---|
17 | .sp |
---|
18 | ClientData |
---|
19 | \fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR |
---|
20 | .sp |
---|
21 | int |
---|
22 | \fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR |
---|
23 | .sp |
---|
24 | void |
---|
25 | \fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR |
---|
26 | .SH ARGUMENTS |
---|
27 | .AS Tcl_CommandTraceProc prevClientData |
---|
28 | .AP Tcl_Interp *interp in |
---|
29 | Interpreter containing the command. |
---|
30 | .AP "const char" *cmdName in |
---|
31 | Name of command. |
---|
32 | .AP int flags in |
---|
33 | OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and |
---|
34 | \fBTCL_TRACE_DELETE\fR. |
---|
35 | .AP Tcl_CommandTraceProc *proc in |
---|
36 | Procedure to call when specified operations occur to \fIcmdName\fR. |
---|
37 | .AP ClientData clientData in |
---|
38 | Arbitrary argument to pass to \fIproc\fR. |
---|
39 | .AP ClientData prevClientData in |
---|
40 | If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR, |
---|
41 | so this call will return information about next trace. If NULL, this |
---|
42 | call will return information about first trace. |
---|
43 | .BE |
---|
44 | .SH DESCRIPTION |
---|
45 | .PP |
---|
46 | \fBTcl_TraceCommand\fR allows a C procedure to monitor operations |
---|
47 | performed on a Tcl command, so that the C procedure is invoked |
---|
48 | whenever the command is renamed or deleted. If the trace is created |
---|
49 | successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error |
---|
50 | occurred (e.g. \fIcmdName\fR specifies a non-existent command) then |
---|
51 | \fBTCL_ERROR\fR is returned and an error message is left in the |
---|
52 | interpreter's result. |
---|
53 | .PP |
---|
54 | The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the |
---|
55 | trace procedure is to be invoked. It consists of an OR'ed combination |
---|
56 | of any of the following values: |
---|
57 | .TP |
---|
58 | \fBTCL_TRACE_RENAME\fR |
---|
59 | Invoke \fIproc\fR whenever the command is renamed. |
---|
60 | .TP |
---|
61 | \fBTCL_TRACE_DELETE\fR |
---|
62 | Invoke \fIproc\fR when the command is deleted. |
---|
63 | .PP |
---|
64 | Whenever one of the specified operations occurs to the command, |
---|
65 | \fIproc\fR will be invoked. It should have arguments and result that |
---|
66 | match the type \fBTcl_CommandTraceProc\fR: |
---|
67 | .CS |
---|
68 | typedef void Tcl_CommandTraceProc( |
---|
69 | ClientData \fIclientData\fR, |
---|
70 | Tcl_Interp *\fIinterp\fR, |
---|
71 | const char *\fIoldName\fR, |
---|
72 | const char *\fInewName\fR, |
---|
73 | int \fIflags\fR); |
---|
74 | .CE |
---|
75 | The \fIclientData\fR and \fIinterp\fR parameters will have the same |
---|
76 | values as those passed to \fBTcl_TraceCommand\fR when the trace was |
---|
77 | created. \fIClientData\fR typically points to an application-specific |
---|
78 | data structure that describes what to do when \fIproc\fR is invoked. |
---|
79 | \fIOldName\fR gives the name of the command being renamed, and |
---|
80 | \fInewName\fR gives the name that the command is being renamed to (or |
---|
81 | an empty string or NULL when the command is being deleted.) |
---|
82 | \fIFlags\fR is an OR'ed combination of bits potentially providing |
---|
83 | several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and |
---|
84 | \fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which |
---|
85 | operation is being performed on the command. The bit |
---|
86 | \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about |
---|
87 | to be destroyed; this information may be useful to \fIproc\fR so that |
---|
88 | it can clean up its own internal data structures (see the section |
---|
89 | \fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit |
---|
90 | \fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being |
---|
91 | destroyed. When this bit is set, \fIproc\fR must be especially |
---|
92 | careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR |
---|
93 | below). |
---|
94 | .PP |
---|
95 | \fBTcl_UntraceCommand\fR may be used to remove a trace. If the |
---|
96 | command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has |
---|
97 | a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then |
---|
98 | the corresponding trace is removed. If no such trace exists, then the |
---|
99 | call to \fBTcl_UntraceCommand\fR has no effect. The same bits are |
---|
100 | valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR. |
---|
101 | .PP |
---|
102 | \fBTcl_CommandTraceInfo\fR may be used to retrieve information about |
---|
103 | traces set on a given command. |
---|
104 | The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR |
---|
105 | associated with a particular trace. |
---|
106 | The trace must be on the command specified by the \fIinterp\fR, |
---|
107 | \fIcmdName\fR, and \fIflags\fR arguments (note that currently the |
---|
108 | flags are ignored; \fIflags\fR should be set to 0 for future |
---|
109 | compatibility) and its trace procedure must the same as the \fIproc\fR |
---|
110 | argument. |
---|
111 | If the \fIprevClientData\fR argument is NULL then the return |
---|
112 | value corresponds to the first (most recently created) matching |
---|
113 | trace, or NULL if there are no matching traces. |
---|
114 | If the \fIprevClientData\fR argument is not NULL, then it should |
---|
115 | be the return value from a previous call to \fBTcl_CommandTraceInfo\fR. |
---|
116 | In this case, the new return value will correspond to the next |
---|
117 | matching trace after the one whose \fIclientData\fR matches |
---|
118 | \fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR |
---|
119 | or if there are no more matching traces after it. |
---|
120 | This mechanism makes it possible to step through all of the |
---|
121 | traces for a given command that have the same \fIproc\fR. |
---|
122 | .SH "CALLING COMMANDS DURING TRACES" |
---|
123 | .PP |
---|
124 | During rename traces, the command being renamed is visible with both |
---|
125 | names simultaneously, and the command still exists during delete |
---|
126 | traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no |
---|
127 | mechanism for signaling that an error occurred in a trace procedure, |
---|
128 | so great care should be taken that errors do not get silently lost. |
---|
129 | .SH "MULTIPLE TRACES" |
---|
130 | .PP |
---|
131 | It is possible for multiple traces to exist on the same command. |
---|
132 | When this happens, all of the trace procedures will be invoked on each |
---|
133 | access, in order from most-recently-created to least-recently-created. |
---|
134 | Attempts to delete the command during a delete trace will fail |
---|
135 | silently, since the command is already scheduled for deletion anyway. |
---|
136 | If the command being renamed is renamed by one of its rename traces, |
---|
137 | that renaming takes precedence over the one that triggered the trace |
---|
138 | and the collection of traces will not be reexecuted; if several traces |
---|
139 | rename the command, the last renaming takes precedence. |
---|
140 | .SH "TCL_TRACE_DESTROYED FLAG" |
---|
141 | .PP |
---|
142 | In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit |
---|
143 | is set in \fIflags\fR. |
---|
144 | .\" Perhaps need some more comments here? - DKF |
---|
145 | .SH "TCL_INTERP_DESTROYED" |
---|
146 | .PP |
---|
147 | When an interpreter is destroyed, unset traces are called for |
---|
148 | all of its commands. |
---|
149 | The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR |
---|
150 | argument passed to the trace procedures. |
---|
151 | Trace procedures must be extremely careful in what they do if |
---|
152 | the \fBTCL_INTERP_DESTROYED\fR bit is set. |
---|
153 | It is not safe for the procedures to invoke any Tcl procedures |
---|
154 | on the interpreter, since its state is partially deleted. |
---|
155 | All that trace procedures should do under these circumstances is |
---|
156 | to clean up and free their own internal data structures. |
---|
157 | .SH BUGS |
---|
158 | .PP |
---|
159 | Tcl does not do any error checking to prevent trace procedures |
---|
160 | from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR |
---|
161 | set. |
---|
162 | .SH KEYWORDS |
---|
163 | clientData, trace, command |
---|