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
16 This command causes Tcl commands to be executed whenever certain opera‐
17 tions are invoked. The legal options (which may be abbreviated) are:
18 trace add type name ops ?args?
20 Where type is command, execution, or variable.
21 trace add command name ops commandPrefix
23 Arrange for commandPrefix to be executed (with additional
24 arguments) whenever command name is modified in one of
25 the ways given by the list ops. Name will be resolved
26 using the usual namespace resolution rules used by com‐
27 mands. If the command does not exist, an error will be
28 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 commandPrefix whenever the traced command
34 is renamed. Note that renaming to the empty
35 string is considered deletion, and will not be
36 traced with “rename”.
37 delete Invoke commandPrefix when the traced command is
39 deleted. Commands can be deleted explicitly by
40 using the rename command to rename the command to
41 an empty string. Commands are also deleted when
42 the interpreter is deleted, but traces will not be
43 invoked because there is no interpreter in which
44 to execute them.
45 When the trace triggers, depending on the operations
47 being traced, a number of arguments are appended to com‐
48 mandPrefix so that the actual command is as follows:
49 commandPrefix 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 commandPrefix
66 Arrange for commandPrefix to be executed (with additional
67 arguments) whenever command name is executed, with traces
68 occurring at the points indicated by the list ops. Name
69 will be resolved using the usual namespace resolution
70 rules used by commands. If the command does not exist,
71 an error will be thrown.
72 Ops indicates which operations are of interest, and is a
74 list of one or more of the following items:
75 enter Invoke commandPrefix whenever the command name is
77 executed, just before the actual execution takes
78 place.
79 leave Invoke commandPrefix whenever the command name is
81 executed, just after the actual execution takes
82 place.
83 enterstep
85 Invoke commandPrefix for every Tcl command which
86 is executed from the start of the execution of the
87 procedure name until that procedure finishes. Com‐
88 mandPrefix is invoked just before the actual exe‐
89 cution of the Tcl command being reported takes
90 place. For example if we have “proc foo {} { puts
91 "hello" }”, then an enterstep trace would be
92 invoked just before “puts "hello"” is executed.
93 Setting an enterstep trace on a command name that
94 does not refer to a procedure will not result in
95 an error and is simply ignored.
96 leavestep
98 Invoke commandPrefix for every Tcl command which
99 is executed from the start of the execution of the
100 procedure name until that procedure finishes. Com‐
101 mandPrefix is invoked just after the actual execu‐
102 tion of the Tcl command being reported takes
103 place. Setting a leavestep trace on a command
104 name that does not refer to a procedure will not
105 result in an error and is simply ignored.
106 When the trace triggers, depending on the operations
108 being traced, a number of arguments are appended to com‐
109 mandPrefix so that the actual command is as follows:
110 For enter and enterstep operations:
112 commandPrefix command-string op
113 Command-string gives the complete current command being
114 executed (the traced command for a enter operation, an
115 arbitrary command for a enterstep operation), including
116 all arguments in their fully expanded form. Op indicates
117 what operation is being performed on the command execu‐
118 tion, and is one of enter or enterstep as defined above.
119 The trace operation can be used to stop the command from
120 executing, by deleting the command in question. Of
121 course when the command is subsequently executed, an
122 “invalid command” error will occur.
123 For leave and leavestep operations:
125 command command-string code result op
126 Command-string gives the complete current command being
127 executed (the traced command for a enter operation, an
128 arbitrary command for a enterstep operation), including
129 all arguments in their fully expanded form. Code gives
130 the result code of that execution, and result the result
131 string. Op indicates what operation is being performed
132 on the command execution, and is one of leave or
133 leavestep as defined above. Note that the creation of
134 many enterstep or leavestep traces can lead to unintu‐
135 itive results, since the invoked commands from one trace
136 can themselves lead to further command invocations for
137 other traces.
138 CommandPrefix executes in the same context as the code
140 that invoked the traced operation: thus the commandPre‐
141 fix, if invoked from a procedure, will have access to the
142 same local variables as code in the procedure. This con‐
143 text may be different than the context in which the trace
144 was created. If commandPrefix invokes a procedure (which
145 it normally does) then the procedure will have to use
146 upvar or uplevel commands if it wishes to access the
147 local variables of the code which invoked the trace oper‐
148 ation.
149 While commandPrefix is executing during an execution
151 trace, traces on name are temporarily disabled. This
152 allows the commandPrefix to execute name in its body
153 without invoking any other traces again. If an error
154 occurs while executing the commandPrefix, then the com‐
155 mand name as a whole will return that same error.
156 When multiple traces are set on name, then for enter and
158 enterstep operations, the traced commands are invoked in
159 the reverse order of how the traces were originally cre‐
160 ated; and for leave and leavestep operations, the traced
161 commands are invoked in the original order of creation.
162 The behavior of execution traces is currently undefined
164 for a command name imported into another namespace.
165 trace add variable name ops commandPrefix
167 Arrange for commandPrefix to be executed whenever vari‐
168 able name is accessed in one of the ways given by the
169 list ops. Name may refer to a normal variable, an ele‐
170 ment of an array, or to an array as a whole (i.e. name
171 may be just the name of an array, with no parenthesized
172 index). If name refers to a whole array, then command‐
173 Prefix is invoked whenever any element of the array is
174 manipulated. If the variable does not exist, it will be
175 created but will not be given a value, so it will be vis‐
176 ible to namespace which queries, but not to info exists
177 queries.
178 Ops indicates which operations are of interest, and is a
180 list of one or more of the following items:
181 array Invoke commandPrefix whenever the variable is
183 accessed or modified via the array command, pro‐
184 vided that name is not a scalar variable at the
185 time that the array command is invoked. If name
186 is a scalar variable, the access via the array
187 command will not trigger the trace.
188 read Invoke commandPrefix whenever the variable is
190 read.
191 write Invoke commandPrefix whenever the variable is
193 written.
194 unset Invoke commandPrefix whenever the variable is
196 unset. Variables can be unset explicitly with the
197 unset command, or implicitly when procedures
198 return (all of their local variables are unset).
199 Variables are also unset when interpreters are
200 deleted, but traces will not be invoked because
201 there is no interpreter in which to execute them.
202 When the trace triggers, three arguments are appended to
204 commandPrefix so that the actual command is as follows:
205 commandPrefix name1 name2 op
206 Name1 and name2 give the name(s) for the variable being
207 accessed: if the variable is a scalar then name1 gives
208 the variable's name and name2 is an empty string; if the
209 variable is an array element then name1 gives the name of
210 the array and name2 gives the index into the array; if an
211 entire array is being deleted and the trace was regis‐
212 tered on the overall array, rather than a single element,
213 then name1 gives the array name and name2 is an empty
214 string. Name1 and name2 are not necessarily the same as
215 the name used in the trace variable command: the upvar
216 command allows a procedure to reference a variable under
217 a different name. Op indicates what operation is being
218 performed on the variable, and is one of read, write, or
219 unset as defined above.
220 CommandPrefix executes in the same context as the code
222 that invoked the traced operation: if the variable was
223 accessed as part of a Tcl procedure, then commandPrefix
224 will have access to the same local variables as code in
225 the procedure. This context may be different than the
226 context in which the trace was created. If commandPrefix
227 invokes a procedure (which it normally does) then the
228 procedure will have to use upvar or uplevel if it wishes
229 to access the traced variable. Note also that name1 may
230 not necessarily be the same as the name used to set the
231 trace on the variable; differences can occur if the
232 access is made through a variable defined with the upvar
233 command.
234 For read and write traces, commandPrefix can modify the
236 variable to affect the result of the traced operation.
237 If commandPrefix modifies the value of a variable during
238 a read or write trace, then the new value will be
239 returned as the result of the traced operation. The
240 return value from commandPrefix is ignored except that
241 if it returns an error of any sort then the traced opera‐
242 tion also returns an error with the same error message
243 returned by the trace command (this mechanism can be used
244 to implement read-only variables, for example). For
245 write traces, commandPrefix is invoked after the vari‐
246 able's value has been changed; it can write a new value
247 into the variable to override the original value speci‐
248 fied in the write operation. To implement read-only
249 variables, commandPrefix will have to restore the old
250 value of the variable.
251 While commandPrefix is executing during a read or write
253 trace, traces on the variable are temporarily disabled.
254 This means that reads and writes invoked by commandPrefix
255 will occur directly, without invoking commandPrefix (or
256 any other traces) again. However, if commandPrefix
257 unsets the variable then unset traces will be invoked.
258 When an unset trace is invoked, the variable has already
260 been deleted: it will appear to be undefined with no
261 traces. If an unset occurs because of a procedure
262 return, then the trace will be invoked in the variable
263 context of the procedure being returned to: the stack
264 frame of the returning procedure will no longer exist.
265 Traces are not disabled during unset traces, so if an
266 unset trace command creates a new trace and accesses the
267 variable, the trace will be invoked. Any errors in unset
268 traces are ignored.
269 If there are multiple traces on a variable they are
271 invoked in order of creation, most-recent first. If one
272 trace returns an error, then no further traces are
273 invoked for the variable. If an array element has a
274 trace set, and there is also a trace set on the array as
275 a whole, the trace on the overall array is invoked before
276 the one on the element.
277 Once created, the trace remains in effect either until
279 the trace is removed with the trace remove variable com‐
280 mand described below, until the variable is unset, or
281 until the interpreter is deleted. Unsetting an element
282 of array will remove any traces on that element, but will
283 not remove traces on the overall array.
284 This command returns an empty string.
286 trace remove type name opList commandPrefix
288 Where type is either command, execution or variable.
289 trace remove command name opList commandPrefix
291 If there is a trace set on command name with the opera‐
292 tions and command given by opList and commandPrefix, then
293 the trace is removed, so that commandPrefix will never
294 again be invoked. Returns an empty string. If name
295 does not exist, the command will throw an error.
296 trace remove execution name opList commandPrefix
298 If there is a trace set on command name with the opera‐
299 tions and command given by opList and commandPrefix, then
300 the trace is removed, so that commandPrefix will never
301 again be invoked. Returns an empty string. If name
302 does not exist, the command will throw an error.
303 trace remove variable name opList commandPrefix
305 If there is a trace set on variable name with the opera‐
306 tions and command given by opList and commandPrefix, then
307 the trace is removed, so that commandPrefix will never
308 again be invoked. Returns an empty string.
309 trace info type name
311 Where type is either command, execution or variable.
312 trace info command name
314 Returns a list containing one element for each trace cur‐
315 rently set on command name. Each element of the list is
316 itself a list containing two elements, which are the
317 opList and commandPrefix associated with the trace. If
318 name does not have any traces set, then the result of the
319 command will be an empty string. If name does not exist,
320 the command will throw an error.
321 trace info execution name
323 Returns a list containing one element for each trace cur‐
324 rently set on command name. Each element of the list is
325 itself a list containing two elements, which are the
326 opList and commandPrefix associated with the trace. If
327 name does not have any traces set, then the result of the
328 command will be an empty string. If name does not exist,
329 the command will throw an error.
330 trace info variable name
332 Returns a list containing one element for each trace cur‐
333 rently set on variable name. Each element of the list is
334 itself a list containing two elements, which are the
335 opList and commandPrefix associated with the trace. If
336 name does not exist or does not have any traces set, then
337 the result of the command will be an empty string.
338 For backwards compatibility, three other subcommands are available:
340 trace variable name ops command
342 This is equivalent to trace add variable name ops com‐
343 mand.
344 trace vdelete name ops command
346 This is equivalent to trace remove variable name ops com‐
347 mand
348 trace vinfo name
350 This is equivalent to trace info variable name
351 These subcommands are deprecated and will likely be removed in a future
353 version of Tcl. They use an older syntax in which array, read, write,
354 unset are replaced by a, r, w and u respectively, and the ops argument
355 is not a list, but simply a string concatenation of the operations,
356 such as rwua.
357
359 Print a message whenever either of the global variables foo and bar are
360 updated, even if they have a different local name at the time (which
361 can be done with the upvar command):
362 proc tracer {varname args} {
363 upvar #0 $varname var
364 puts "$varname was updated to be \"$var\""
365 }
366 trace add variable foo write "tracer foo"
367 trace add variable bar write "tracer bar"
368 Ensure that the global variable foobar always contains the product of
370 the global variables foo and bar:
371 proc doMult args {
372 global foo bar foobar
373 set foobar [expr {$foo * $bar}]
374 }
375 trace add variable foo write doMult
376 trace add variable bar write doMult
377 Print a trace of what commands are executed during the processing of a
379 Tcl procedure:
380 proc x {} { y }
381 proc y {} { z }
382 proc z {} { puts hello }
383 proc report args {puts [info level 0]}
384 trace add execution x enterstep report
385 x
386 → report y enterstep
387 report z enterstep
388 report {puts hello} enterstep
389 hello
390
392 set(n), unset(n)
393
395 read, command, rename, variable, write, trace, unset
396Tcl 8.4 trace(n)