1trace(n) Tcl Built-In Commands trace(n)
2______________________________________________________________________________
6
8 trace - Monitor variable accesses, command usages and command execu‐
9 tions
10
12 trace option ?arg arg ...?
13_________________________________________________________________
14
17 This command causes Tcl commands to be executed whenever certain opera‐
18 tions are invoked. The legal option's (which may be abbreviated) are:
19 trace add type name ops ?args?
21 Where type is command, execution, or variable.
22 trace add command name ops command
24 Arrange for command to be executed whenever command name
25 is modified in one of the ways given by the list ops.
26 Name will be resolved using the usual namespace resolu‐
27 tion rules used by procedures. If the command does not
28 exist, an error will be thrown.
29 Ops indicates which operations are of interest, and is a
31 list of one or more of the following items:
32 rename Invoke command whenever the command is renamed.
34 Note that renaming to the empty string is consid‐
35 ered deletion, and will not be traced with
36 'rename'.
37 delete Invoke command when the command is deleted. Com‐
39 mands can be deleted explicitly by using the
40 rename command to rename the command to an empty
41 string. Commands are also deleted when the inter‐
42 preter is deleted, but traces will not be invoked
43 because there is no interpreter in which to exe‐
44 cute them.
45 When the trace triggers, depending on the operations
47 being traced, a number of arguments are appended to com‐
48 mand so that the actual command is as follows:
49 command oldName newName op
50 OldName and newName give the traced command's current
51 (old) name, and the name to which it is being renamed
52 (the empty string if this is a 'delete' operation). Op
53 indicates what operation is being performed on the com‐
54 mand, and is one of rename or delete as defined above.
55 The trace operation cannot be used to stop a command from
56 being deleted. Tcl will always remove the command once
57 the trace is complete. Recursive renaming or deleting
58 will not cause further traces of the same type to be
59 evaluated, so a delete trace which itself deletes the
60 command, or a rename trace which itself renames the com‐
61 mand will not cause further trace evaluations to occur.
62 Both oldName and newName are fully qualified with any
63 namespace(s) in which they appear.
64 trace add execution name ops command
66 Arrange for command to be executed whenever command name
67 is executed, with traces occurring at the points indi‐
68 cated by the list ops. Name will be resolved using the
69 usual namespace resolution rules used by procedures. If
70 the command does not exist, an error will be thrown.
71 Ops indicates which operations are of interest, and is a
73 list of one or more of the following items:
74 enter Invoke command whenever the command name is exe‐
76 cuted, just before the actual execution takes
77 place.
78 leave Invoke command whenever the command name is exe‐
80 cuted, just after the actual execution takes
81 place.
82 enterstep
84 Invoke command for every Tcl command which is exe‐
85 cuted inside the procedure name, just before the
86 actual execution takes place. For example if we
87 have 'proc foo {} { puts "hello" }', then an
88 enterstep trace would be invoked just before puts
89 "hello" is executed. Setting an enterstep trace
90 on a command will not result in an error and is
91 simply ignored.
92 leavestep
94 Invoke command for every Tcl command which is exe‐
95 cuted inside the procedure name, just after the
96 actual execution takes place. Setting a leavestep
97 trace on a command will not result in an error and
98 is simply ignored.
99 When the trace triggers, depending on the operations
101 being traced, a number of arguments are appended to com‐
102 mand so that the actual command is as follows:
103 For enter and enterstep operations:
105 command command-string op
106 Command-string gives the complete current command being
107 executed (the traced command for a enter operation, an
108 arbitrary command for a enterstep operation), including
109 all arguments in their fully expanded form. Op indicates
110 what operation is being performed on the command execu‐
111 tion, and is one of enter or enterstep as defined above.
112 The trace operation can be used to stop the command from
113 executing, by deleting the command in question. Of
114 course when the command is subsequently executed, an
115 'invalid command' error will occur.
116 For leave and leavestep operations:
118 command command-string code result op
119 Command-string gives the complete current command being
120 executed (the traced command for a enter operation, an
121 arbitrary command for a enterstep operation), including
122 all arguments in their fully expanded form. Code gives
123 the result code of that execution, and result the result
124 string. Op indicates what operation is being performed
125 on the command execution, and is one of leave or
126 leavestep as defined above. Note that the creation of
127 many enterstep or leavestep traces can lead to unintu‐
128 itive results, since the invoked commands from one trace
129 can themselves lead to further command invocations for
130 other traces.
131 Command executes in the same context as the code that
133 invoked the traced operation: thus the command, if
134 invoked from a procedure, will have access to the same
135 local variables as code in the procedure. This context
136 may be different than the context in which the trace was
137 created. If command invokes a procedure (which it nor‐
138 mally does) then the procedure will have to use upvar or
139 uplevel commands if it wishes to access the local vari‐
140 ables of the code which invoked the trace operation.
141 While command is executing during an execution trace,
143 traces on name are temporarily disabled. This allows the
144 command to execute name in its body without invoking any
145 other traces again. If an error occurs while executing
146 the command body, then the command name as a whole will
147 return that same error.
148 When multiple traces are set on name, then for enter and
150 enterstep operations, the traced commands are invoked in
151 the reverse order of how the traces were originally cre‐
152 ated; and for leave and leavestep operations, the traced
153 commands are invoked in the original order of creation.
154 The behavior of execution traces is currently undefined
156 for a command name imported into another namespace.
157 trace add variable name ops command
159 Arrange for command to be executed whenever variable name
160 is accessed in one of the ways given by the list ops.
161 Name may refer to a normal variable, an element of an
162 array, or to an array as a whole (i.e. name may be just
163 the name of an array, with no parenthesized index). If
164 name refers to a whole array, then command is invoked
165 whenever any element of the array is manipulated. If the
166 variable does not exist, it will be created but will not
167 be given a value, so it will be visible to namespace
168 which queries, but not to info exists queries.
169 Ops indicates which operations are of interest, and is a
171 list of one or more of the following items:
172 array Invoke command whenever the variable is accessed
174 or modified via the array command, provided that
175 name is not a scalar variable at the time that the
176 array command is invoked. If name is a scalar
177 variable, the access via the array command will
178 not trigger the trace.
179 read Invoke command whenever the variable is read.
181 write Invoke command whenever the variable is written.
183 unset Invoke command whenever the variable is unset.
185 Variables can be unset explicitly with the unset
186 command, or implicitly when procedures return (all
187 of their local variables are unset). Variables
188 are also unset when interpreters are deleted, but
189 traces will not be invoked because there is no
190 interpreter in which to execute them.
191 When the trace triggers, three arguments are appended to
193 command so that the actual command is as follows:
194 command name1 name2 op
195 Name1 and name2 give the name(s) for the variable being
196 accessed: if the variable is a scalar then name1 gives
197 the variable's name and name2 is an empty string; if the
198 variable is an array element then name1 gives the name of
199 the array and name2 gives the index into the array; if an
200 entire array is being deleted and the trace was regis‐
201 tered on the overall array, rather than a single element,
202 then name1 gives the array name and name2 is an empty
203 string. Name1 and name2 are not necessarily the same as
204 the name used in the trace variable command: the upvar
205 command allows a procedure to reference a variable under
206 a different name. Op indicates what operation is being
207 performed on the variable, and is one of read, write, or
208 unset as defined above.
209 Command executes in the same context as the code that
211 invoked the traced operation: if the variable was
212 accessed as part of a Tcl procedure, then command will
213 have access to the same local variables as code in the
214 procedure. This context may be different than the con‐
215 text in which the trace was created. If command invokes a
216 procedure (which it normally does) then the procedure
217 will have to use upvar or uplevel if it wishes to access
218 the traced variable. Note also that name1 may not neces‐
219 sarily be the same as the name used to set the trace on
220 the variable; differences can occur if the access is made
221 through a variable defined with the upvar command.
222 For read and write traces, command can modify the vari‐
224 able to affect the result of the traced operation. If
225 command modifies the value of a variable during a read or
226 write trace, then the new value will be returned as the
227 result of the traced operation. The return value from
228 command is ignored except that if it returns an error of
229 any sort then the traced operation also returns an error
230 with the same error message returned by the trace command
231 (this mechanism can be used to implement read-only vari‐
232 ables, for example). For write traces, command is
233 invoked after the variable's value has been changed; it
234 can write a new value into the variable to override the
235 original value specified in the write operation. To
236 implement read-only variables, command will have to
237 restore the old value of the variable.
238 While command is executing during a read or write trace,
240 traces on the variable are temporarily disabled. This
241 means that reads and writes invoked by command will occur
242 directly, without invoking command (or any other traces)
243 again. However, if command unsets the variable then
244 unset traces will be invoked.
245 When an unset trace is invoked, the variable has already
247 been deleted: it will appear to be undefined with no
248 traces. If an unset occurs because of a procedure
249 return, then the trace will be invoked in the variable
250 context of the procedure being returned to: the stack
251 frame of the returning procedure will no longer exist.
252 Traces are not disabled during unset traces, so if an
253 unset trace command creates a new trace and accesses the
254 variable, the trace will be invoked. Any errors in unset
255 traces are ignored.
256 If there are multiple traces on a variable they are
258 invoked in order of creation, most-recent first. If one
259 trace returns an error, then no further traces are
260 invoked for the variable. If an array element has a
261 trace set, and there is also a trace set on the array as
262 a whole, the trace on the overall array is invoked before
263 the one on the element.
264 Once created, the trace remains in effect either until
266 the trace is removed with the trace remove variable com‐
267 mand described below, until the variable is unset, or
268 until the interpreter is deleted. Unsetting an element
269 of array will remove any traces on that element, but will
270 not remove traces on the overall array.
271 This command returns an empty string.
273 trace remove type name opList command
275 Where type is either command, execution or variable.
276 trace remove command name opList command
278 If there is a trace set on command name with the opera‐
279 tions and command given by opList and command, then the
280 trace is removed, so that command will never again be
281 invoked. Returns an empty string. If name doesn't
282 exist, the command will throw an error.
283 trace remove execution name opList command
285 If there is a trace set on command name with the opera‐
286 tions and command given by opList and command, then the
287 trace is removed, so that command will never again be
288 invoked. Returns an empty string. If name doesn't
289 exist, the command will throw an error.
290 trace remove variable name opList command
292 If there is a trace set on variable name with the opera‐
293 tions and command given by opList and command, then the
294 trace is removed, so that command will never again be
295 invoked. Returns an empty string.
296 trace info type name
298 Where type is either command, execution or variable.
299 trace info command name
301 Returns a list containing one element for each trace cur‐
302 rently set on command name. Each element of the list is
303 itself a list containing two elements, which are the
304 opList and command associated with the trace. If name
305 doesn't have any traces set, then the result of the com‐
306 mand will be an empty string. If name doesn't exist, the
307 command will throw an error.
308 trace info execution name
310 Returns a list containing one element for each trace cur‐
311 rently set on command name. Each element of the list is
312 itself a list containing two elements, which are the
313 opList and command associated with the trace. If name
314 doesn't have any traces set, then the result of the com‐
315 mand will be an empty string. If name doesn't exist, the
316 command will throw an error.
317 trace info variable name
319 Returns a list containing one element for each trace cur‐
320 rently set on variable name. Each element of the list is
321 itself a list containing two elements, which are the
322 opList and command associated with the trace. If name
323 doesn't exist or doesn't have any traces set, then the
324 result of the command will be an empty string.
325 For backwards compatibility, three other subcommands are available:
327 trace variable name ops command
329 This is equivalent to trace add variable name ops com‐
330 mand.
331 trace vdelete name ops command
333 This is equivalent to trace remove variable name ops com‐
334 mand
335 trace vinfo name
337 This is equivalent to trace info variable name
338 These subcommands are deprecated and will likely be removed in a future
340 version of Tcl. They use an older syntax in which array, read, write,
341 unset are replaced by a, r, w and u respectively, and the ops argument
342 is not a list, but simply a string concatenation of the operations,
343 such as rwua.
344
346 Print a message whenever either of the global variables foo and bar are
347 updated, even if they have a different local name at the time (which
348 can be done with the upvar command):
349 proc tracer {varname args} {
350 upvar #0 $varname var
351 puts "$varname was updated to be \"$var\""
352 }
353 trace add variable foo write "tracer foo"
354 trace add variable bar write "tracer bar"
355 Ensure that the global variable foobar always contains the product of
357 the global variables foo and bar:
358 proc doMult args {
359 global foo bar foobar
360 set foobar [expr {$foo * $bar}]
361 }
362 trace add variable foo write doMult
363 trace add variable bar write doMult
364
367 set(n), unset(n)
368
371 read, command, rename, variable, write, trace, unset
372Tcl 8.4 trace(n)