1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 2000 Ajuba Solutions. |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: trace.n,v 1.26 2007/12/13 15:22:33 dgp Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH trace n "8.4" Tcl "Tcl Built-In Commands" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | trace \- Monitor variable accesses, command usages and command executions |
---|
17 | .SH SYNOPSIS |
---|
18 | \fBtrace \fIoption\fR ?\fIarg arg ...\fR? |
---|
19 | .BE |
---|
20 | .SH DESCRIPTION |
---|
21 | .PP |
---|
22 | This command causes Tcl commands to be executed whenever certain operations are |
---|
23 | invoked. The legal \fIoption\fRs (which may be abbreviated) are: |
---|
24 | .TP |
---|
25 | \fBtrace add \fItype name ops ?args?\fR |
---|
26 | Where \fItype\fR is \fBcommand\fR, \fBexecution\fR, or \fBvariable\fR. |
---|
27 | .RS |
---|
28 | .TP |
---|
29 | \fBtrace add command\fR \fIname ops commandPrefix\fR |
---|
30 | . |
---|
31 | Arrange for \fIcommandPrefix\fR to be executed (with additional arguments) |
---|
32 | whenever command \fIname\fR is modified in one of the ways given by the list |
---|
33 | \fIops\fR. \fIName\fR will be resolved using the usual namespace resolution |
---|
34 | rules used by commands. If the command does not exist, an error will be |
---|
35 | thrown. |
---|
36 | .RS |
---|
37 | .PP |
---|
38 | \fIOps\fR indicates which operations are of interest, and is a list of |
---|
39 | one or more of the following items: |
---|
40 | .TP |
---|
41 | \fBrename\fR |
---|
42 | . |
---|
43 | Invoke \fIcommandPrefix\fR whenever the traced command is renamed. Note that |
---|
44 | renaming to the empty string is considered deletion, and will not be traced |
---|
45 | with |
---|
46 | .QW \fBrename\fR . |
---|
47 | .TP |
---|
48 | \fBdelete\fR |
---|
49 | . |
---|
50 | Invoke \fIcommandPrefix\fR when the traced command is deleted. Commands can be |
---|
51 | deleted explicitly by using the \fBrename\fR command to rename the command to |
---|
52 | an empty string. Commands are also deleted when the interpreter is deleted, |
---|
53 | but traces will not be invoked because there is no interpreter in which to |
---|
54 | execute them. |
---|
55 | .PP |
---|
56 | When the trace triggers, depending on the operations being traced, a number of |
---|
57 | arguments are appended to \fIcommandPrefix\fR so that the actual command is as |
---|
58 | follows: |
---|
59 | .CS |
---|
60 | \fIcommandPrefix oldName newName op\fR |
---|
61 | .CE |
---|
62 | \fIOldName\fR and \fInewName\fR give the traced command's current (old) name, |
---|
63 | and the name to which it is being renamed (the empty string if this is a |
---|
64 | .QW delete |
---|
65 | operation). |
---|
66 | \fIOp\fR indicates what operation is being performed on the |
---|
67 | command, and is one of \fBrename\fR or \fBdelete\fR as |
---|
68 | defined above. The trace operation cannot be used to stop a command |
---|
69 | from being deleted. Tcl will always remove the command once the trace |
---|
70 | is complete. Recursive renaming or deleting will not cause further traces |
---|
71 | of the same type to be evaluated, so a delete trace which itself |
---|
72 | deletes the command, or a rename trace which itself renames the |
---|
73 | command will not cause further trace evaluations to occur. |
---|
74 | Both \fIoldName\fR and \fInewName\fR are fully qualified with any namespace(s) |
---|
75 | in which they appear. |
---|
76 | .RE |
---|
77 | .TP |
---|
78 | \fBtrace add execution\fR \fIname ops commandPrefix\fR |
---|
79 | . |
---|
80 | Arrange for \fIcommandPrefix\fR to be executed (with additional arguments) |
---|
81 | whenever command \fIname\fR is executed, with traces occurring at the points |
---|
82 | indicated by the list \fIops\fR. \fIName\fR will be resolved using the usual |
---|
83 | namespace resolution rules used by commands. If the command does not exist, |
---|
84 | an error will be thrown. |
---|
85 | .RS |
---|
86 | .PP |
---|
87 | \fIOps\fR indicates which operations are of interest, and is a list of |
---|
88 | one or more of the following items: |
---|
89 | .TP |
---|
90 | \fBenter\fR |
---|
91 | Invoke \fIcommandPrefix\fR whenever the command \fIname\fR is executed, |
---|
92 | just before the actual execution takes place. |
---|
93 | .TP |
---|
94 | \fBleave\fR |
---|
95 | Invoke \fIcommandPrefix\fR whenever the command \fIname\fR is executed, |
---|
96 | just after the actual execution takes place. |
---|
97 | .TP |
---|
98 | \fBenterstep\fR |
---|
99 | . |
---|
100 | Invoke \fIcommandPrefix\fR for every Tcl command which is executed from the |
---|
101 | start of the execution of the procedure \fIname\fR until that |
---|
102 | procedure finishes. \fICommandPrefix\fR is invoked just before the actual |
---|
103 | execution of the Tcl command being reported takes place. For example |
---|
104 | if we have |
---|
105 | .QW "proc foo {} { puts \N'34'hello\N'34' }" , |
---|
106 | then an \fIenterstep\fR trace would be invoked just before |
---|
107 | .QW "\fIputs \N'34'hello\N'34'\fR" |
---|
108 | is executed. |
---|
109 | Setting an \fIenterstep\fR trace on a command \fIname\fR that does not refer |
---|
110 | to a procedure will not result in an error and is simply ignored. |
---|
111 | .TP |
---|
112 | \fBleavestep\fR |
---|
113 | . |
---|
114 | Invoke \fIcommandPrefix\fR for every Tcl command which is executed from the |
---|
115 | start of the execution of the procedure \fIname\fR until that |
---|
116 | procedure finishes. \fICommandPrefix\fR is invoked just after the actual |
---|
117 | execution of the Tcl command being reported takes place. |
---|
118 | Setting a \fIleavestep\fR trace on a command \fIname\fR that does not refer to |
---|
119 | a procedure will not result in an error and is simply ignored. |
---|
120 | .PP |
---|
121 | When the trace triggers, depending on the operations being traced, a |
---|
122 | number of arguments are appended to \fIcommandPrefix\fR so that the actual |
---|
123 | command is as follows: |
---|
124 | .PP |
---|
125 | For \fBenter\fR and \fBenterstep\fR operations: |
---|
126 | .CS |
---|
127 | \fIcommandPrefix command-string op\fR |
---|
128 | .CE |
---|
129 | \fICommand-string\fR gives the complete current command being |
---|
130 | executed (the traced command for a \fBenter\fR operation, an |
---|
131 | arbitrary command for a \fBenterstep\fR operation), including |
---|
132 | all arguments in their fully expanded form. |
---|
133 | \fIOp\fR indicates what operation is being performed on the |
---|
134 | command execution, and is one of \fBenter\fR or \fBenterstep\fR as |
---|
135 | defined above. The trace operation can be used to stop the |
---|
136 | command from executing, by deleting the command in question. Of |
---|
137 | course when the command is subsequently executed, an |
---|
138 | .QW "invalid command" |
---|
139 | error will occur. |
---|
140 | .PP |
---|
141 | For \fBleave\fR and \fBleavestep\fR operations: |
---|
142 | .CS |
---|
143 | \fIcommand command-string code result op\fR |
---|
144 | .CE |
---|
145 | \fICommand-string\fR gives the complete current command being |
---|
146 | executed (the traced command for a \fBenter\fR operation, an |
---|
147 | arbitrary command for a \fBenterstep\fR operation), including |
---|
148 | all arguments in their fully expanded form. |
---|
149 | \fICode\fR gives the result code of that execution, and \fIresult\fR |
---|
150 | the result string. |
---|
151 | \fIOp\fR indicates what operation is being performed on the |
---|
152 | command execution, and is one of \fBleave\fR or \fBleavestep\fR as |
---|
153 | defined above. |
---|
154 | Note that the creation of many \fBenterstep\fR or |
---|
155 | \fBleavestep\fR traces can lead to unintuitive results, since the |
---|
156 | invoked commands from one trace can themselves lead to further |
---|
157 | command invocations for other traces. |
---|
158 | .PP |
---|
159 | \fICommandPrefix\fR executes in the same context as the code that invoked |
---|
160 | the traced operation: thus the \fIcommandPrefix\fR, if invoked from a |
---|
161 | procedure, will have access to the same local variables as code in the |
---|
162 | procedure. This context may be different than the context in which the trace |
---|
163 | was created. If \fIcommandPrefix\fR invokes a procedure (which it normally |
---|
164 | does) then the procedure will have to use \fBupvar\fR or \fBuplevel\fR |
---|
165 | commands if it wishes to access the local variables of the code which invoked |
---|
166 | the trace operation. |
---|
167 | .PP |
---|
168 | While \fIcommandPrefix\fR is executing during an execution trace, traces |
---|
169 | on \fIname\fR are temporarily disabled. This allows the \fIcommandPrefix\fR |
---|
170 | to execute \fIname\fR in its body without invoking any other traces again. |
---|
171 | If an error occurs while executing the \fIcommandPrefix\fR, then the |
---|
172 | command \fIname\fR as a whole will return that same error. |
---|
173 | .PP |
---|
174 | When multiple traces are set on \fIname\fR, then for \fIenter\fR |
---|
175 | and \fIenterstep\fR operations, the traced commands are invoked |
---|
176 | in the reverse order of how the traces were originally created; |
---|
177 | and for \fIleave\fR and \fIleavestep\fR operations, the traced |
---|
178 | commands are invoked in the original order of creation. |
---|
179 | .PP |
---|
180 | The behavior of execution traces is currently undefined for a command |
---|
181 | \fIname\fR imported into another namespace. |
---|
182 | .RE |
---|
183 | .TP |
---|
184 | \fBtrace add variable\fI name ops commandPrefix\fR |
---|
185 | Arrange for \fIcommandPrefix\fR to be executed whenever variable \fIname\fR |
---|
186 | is accessed in one of the ways given by the list \fIops\fR. \fIName\fR may |
---|
187 | refer to a normal variable, an element of an array, or to an array |
---|
188 | as a whole (i.e. \fIname\fR may be just the name of an array, with no |
---|
189 | parenthesized index). If \fIname\fR refers to a whole array, then |
---|
190 | \fIcommandPrefix\fR is invoked whenever any element of the array is |
---|
191 | manipulated. If the variable does not exist, it will be created but |
---|
192 | will not be given a value, so it will be visible to \fBnamespace which\fR |
---|
193 | queries, but not to \fBinfo exists\fR queries. |
---|
194 | .RS |
---|
195 | .PP |
---|
196 | \fIOps\fR indicates which operations are of interest, and is a list of |
---|
197 | one or more of the following items: |
---|
198 | .TP |
---|
199 | \fBarray\fR |
---|
200 | Invoke \fIcommandPrefix\fR whenever the variable is accessed or modified via |
---|
201 | the \fBarray\fR command, provided that \fIname\fR is not a scalar |
---|
202 | variable at the time that the \fBarray\fR command is invoked. If |
---|
203 | \fIname\fR is a scalar variable, the access via the \fBarray\fR |
---|
204 | command will not trigger the trace. |
---|
205 | .TP |
---|
206 | \fBread\fR |
---|
207 | Invoke \fIcommandPrefix\fR whenever the variable is read. |
---|
208 | .TP |
---|
209 | \fBwrite\fR |
---|
210 | Invoke \fIcommandPrefix\fR whenever the variable is written. |
---|
211 | .TP |
---|
212 | \fBunset\fR |
---|
213 | Invoke \fIcommandPrefix\fR whenever the variable is unset. Variables |
---|
214 | can be unset explicitly with the \fBunset\fR command, or |
---|
215 | implicitly when procedures return (all of their local variables |
---|
216 | are unset). Variables are also unset when interpreters are |
---|
217 | deleted, but traces will not be invoked because there is no |
---|
218 | interpreter in which to execute them. |
---|
219 | .PP |
---|
220 | When the trace triggers, three arguments are appended to |
---|
221 | \fIcommandPrefix\fR so that the actual command is as follows: |
---|
222 | .CS |
---|
223 | \fIcommandPrefix name1 name2 op\fR |
---|
224 | .CE |
---|
225 | \fIName1\fR and \fIname2\fR give the name(s) for the variable |
---|
226 | being accessed: if the variable is a scalar then \fIname1\fR |
---|
227 | gives the variable's name and \fIname2\fR is an empty string; |
---|
228 | if the variable is an array element then \fIname1\fR gives the |
---|
229 | name of the array and name2 gives the index into the array; |
---|
230 | if an entire array is being deleted and the trace was registered |
---|
231 | on the overall array, rather than a single element, then \fIname1\fR |
---|
232 | gives the array name and \fIname2\fR is an empty string. |
---|
233 | \fIName1\fR and \fIname2\fR are not necessarily the same as the |
---|
234 | name used in the \fBtrace variable\fR command: the \fBupvar\fR |
---|
235 | command allows a procedure to reference a variable under a |
---|
236 | different name. |
---|
237 | \fIOp\fR indicates what operation is being performed on the |
---|
238 | variable, and is one of \fBread\fR, \fBwrite\fR, or \fBunset\fR as |
---|
239 | defined above. |
---|
240 | .PP |
---|
241 | \fICommandPrefix\fR executes in the same context as the code that invoked |
---|
242 | the traced operation: if the variable was accessed as part of a Tcl |
---|
243 | procedure, then \fIcommandPrefix\fR will have access to the same local |
---|
244 | variables as code in the procedure. This context may be different |
---|
245 | than the context in which the trace was created. If \fIcommandPrefix\fR |
---|
246 | invokes a procedure (which it normally does) then the procedure will |
---|
247 | have to use \fBupvar\fR or \fBuplevel\fR if it wishes to access the |
---|
248 | traced variable. Note also that \fIname1\fR may not necessarily be |
---|
249 | the same as the name used to set the trace on the variable; |
---|
250 | differences can occur if the access is made through a variable defined |
---|
251 | with the \fBupvar\fR command. |
---|
252 | .PP |
---|
253 | For read and write traces, \fIcommandPrefix\fR can modify the variable to |
---|
254 | affect the result of the traced operation. If \fIcommandPrefix\fR modifies |
---|
255 | the value of a variable during a read or write trace, then the new |
---|
256 | value will be returned as the result of the traced operation. The |
---|
257 | return value from \fIcommandPrefix\fR is ignored except that if it returns |
---|
258 | an error of any sort then the traced operation also returns an error |
---|
259 | with the same error message returned by the trace command (this |
---|
260 | mechanism can be used to implement read-only variables, for example). |
---|
261 | For write traces, \fIcommandPrefix\fR is invoked after the variable's value |
---|
262 | has been changed; it can write a new value into the variable to |
---|
263 | override the original value specified in the write operation. To |
---|
264 | implement read-only variables, \fIcommandPrefix\fR will have to restore the |
---|
265 | old value of the variable. |
---|
266 | .PP |
---|
267 | While \fIcommandPrefix\fR is executing during a read or write trace, traces |
---|
268 | on the variable are temporarily disabled. This means that reads and |
---|
269 | writes invoked by \fIcommandPrefix\fR will occur directly, without invoking |
---|
270 | \fIcommandPrefix\fR (or any other traces) again. However, if |
---|
271 | \fIcommandPrefix\fR unsets the variable then unset traces will be invoked. |
---|
272 | .PP |
---|
273 | When an unset trace is invoked, the variable has already been deleted: |
---|
274 | it will appear to be undefined with no traces. If an unset occurs |
---|
275 | because of a procedure return, then the trace will be invoked in the |
---|
276 | variable context of the procedure being returned to: the stack frame |
---|
277 | of the returning procedure will no longer exist. Traces are not |
---|
278 | disabled during unset traces, so if an unset trace command creates a |
---|
279 | new trace and accesses the variable, the trace will be invoked. Any |
---|
280 | errors in unset traces are ignored. |
---|
281 | .PP |
---|
282 | If there are multiple traces on a variable they are invoked in order |
---|
283 | of creation, most-recent first. If one trace returns an error, then |
---|
284 | no further traces are invoked for the variable. If an array element |
---|
285 | has a trace set, and there is also a trace set on the array as a |
---|
286 | whole, the trace on the overall array is invoked before the one on the |
---|
287 | element. |
---|
288 | .PP |
---|
289 | Once created, the trace remains in effect either until the trace is |
---|
290 | removed with the \fBtrace remove variable\fR command described below, |
---|
291 | until the variable is unset, or until the interpreter is deleted. |
---|
292 | Unsetting an element of array will remove any traces on that element, |
---|
293 | but will not remove traces on the overall array. |
---|
294 | .PP |
---|
295 | This command returns an empty string. |
---|
296 | .RE |
---|
297 | .RE |
---|
298 | .TP |
---|
299 | \fBtrace remove \fItype name opList commandPrefix\fR |
---|
300 | Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR. |
---|
301 | .RS |
---|
302 | .TP |
---|
303 | \fBtrace remove command\fI name opList commandPrefix\fR |
---|
304 | If there is a trace set on command \fIname\fR with the operations and |
---|
305 | command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is |
---|
306 | removed, so that \fIcommandPrefix\fR will never again be invoked. Returns |
---|
307 | an empty string. If \fIname\fR does not exist, the command will throw |
---|
308 | an error. |
---|
309 | .TP |
---|
310 | \fBtrace remove execution\fI name opList commandPrefix\fR |
---|
311 | If there is a trace set on command \fIname\fR with the operations and |
---|
312 | command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is |
---|
313 | removed, so that \fIcommandPrefix\fR will never again be invoked. Returns |
---|
314 | an empty string. If \fIname\fR does not exist, the command will throw |
---|
315 | an error. |
---|
316 | .TP |
---|
317 | \fBtrace remove variable\fI name opList commandPrefix\fR |
---|
318 | If there is a trace set on variable \fIname\fR with the operations and |
---|
319 | command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is |
---|
320 | removed, so that \fIcommandPrefix\fR will never again be invoked. Returns |
---|
321 | an empty string. |
---|
322 | .RE |
---|
323 | .TP |
---|
324 | \fBtrace info \fItype name\fR |
---|
325 | Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR. |
---|
326 | .RS |
---|
327 | .TP |
---|
328 | \fBtrace info command\fI name\fR |
---|
329 | Returns a list containing one element for each trace currently set on |
---|
330 | command \fIname\fR. Each element of the list is itself a list |
---|
331 | containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR |
---|
332 | associated with the trace. If \fIname\fR does not have any traces set, |
---|
333 | then the result of the command will be an empty string. If \fIname\fR |
---|
334 | does not exist, the command will throw an error. |
---|
335 | .TP |
---|
336 | \fBtrace info execution\fI name\fR |
---|
337 | Returns a list containing one element for each trace currently set on |
---|
338 | command \fIname\fR. Each element of the list is itself a list |
---|
339 | containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR |
---|
340 | associated with the trace. If \fIname\fR does not have any traces set, |
---|
341 | then the result of the command will be an empty string. If \fIname\fR |
---|
342 | does not exist, the command will throw an error. |
---|
343 | .TP |
---|
344 | \fBtrace info variable\fI name\fR |
---|
345 | Returns a list containing one element for each trace currently set on |
---|
346 | variable \fIname\fR. Each element of the list is itself a list |
---|
347 | containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR |
---|
348 | associated with the trace. If \fIname\fR does not exist or does not |
---|
349 | have any traces set, then the result of the command will be an empty |
---|
350 | string. |
---|
351 | .RE |
---|
352 | .PP |
---|
353 | For backwards compatibility, three other subcommands are available: |
---|
354 | .RS |
---|
355 | .TP |
---|
356 | \fBtrace variable \fIname ops command\fR |
---|
357 | This is equivalent to \fBtrace add variable \fIname ops command\fR. |
---|
358 | .TP |
---|
359 | \fBtrace vdelete \fIname ops command\fR |
---|
360 | This is equivalent to \fBtrace remove variable \fIname ops command\fR |
---|
361 | .TP |
---|
362 | \fBtrace vinfo \fIname\fR |
---|
363 | This is equivalent to \fBtrace info variable \fIname\fR |
---|
364 | .RE |
---|
365 | .PP |
---|
366 | These subcommands are deprecated and will likely be removed in a |
---|
367 | future version of Tcl. They use an older syntax in which \fBarray\fR, |
---|
368 | \fBread\fR, \fBwrite\fR, \fBunset\fR are replaced by \fBa\fR, \fBr\fR, |
---|
369 | \fBw\fR and \fBu\fR respectively, and the \fIops\fR argument is not a |
---|
370 | list, but simply a string concatenation of the operations, such as |
---|
371 | \fBrwua\fR. |
---|
372 | .SH EXAMPLES |
---|
373 | Print a message whenever either of the global variables \fBfoo\fR and |
---|
374 | \fBbar\fR are updated, even if they have a different local name at the |
---|
375 | time (which can be done with the \fBupvar\fR command): |
---|
376 | .CS |
---|
377 | proc tracer {varname args} { |
---|
378 | upvar #0 $varname var |
---|
379 | puts "$varname was updated to be \e"$var\e"" |
---|
380 | } |
---|
381 | \fBtrace add\fR variable foo write "tracer foo" |
---|
382 | \fBtrace add\fR variable bar write "tracer bar" |
---|
383 | .CE |
---|
384 | .PP |
---|
385 | Ensure that the global variable \fBfoobar\fR always contains the |
---|
386 | product of the global variables \fBfoo\fR and \fBbar\fR: |
---|
387 | .CS |
---|
388 | proc doMult args { |
---|
389 | global foo bar foobar |
---|
390 | set foobar [expr {$foo * $bar}] |
---|
391 | } |
---|
392 | \fBtrace add\fR variable foo write doMult |
---|
393 | \fBtrace add\fR variable bar write doMult |
---|
394 | .CE |
---|
395 | .PP |
---|
396 | Print a trace of what commands are executed during the processing of a Tcl |
---|
397 | procedure: |
---|
398 | .CS |
---|
399 | proc x {} { y } |
---|
400 | proc y {} { z } |
---|
401 | proc z {} { puts hello } |
---|
402 | proc report args {puts [info level 0]} |
---|
403 | \fBtrace add\fR execution x enterstep report |
---|
404 | x |
---|
405 | \(-> \fIreport y enterstep\fR |
---|
406 | \fIreport z enterstep\fR |
---|
407 | \fIreport {puts hello} enterstep\fR |
---|
408 | \fIhello\fR |
---|
409 | .CE |
---|
410 | .SH "SEE ALSO" |
---|
411 | set(n), unset(n) |
---|
412 | .SH KEYWORDS |
---|
413 | read, command, rename, variable, write, trace, unset |
---|