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