1trace(n)                     Tcl Built-In Commands                    trace(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       trace  -  Monitor  variable accesses, command usages and command execu‐
9       tions
10

SYNOPSIS

12       trace option ?arg arg ...?
13______________________________________________________________________________
14

DESCRIPTION

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
19       trace add type name ops ?args?
20              Where type is command, execution, or variable.
21
22              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
30                     Ops indicates which operations are of interest, and is  a
31                     list of one or more of the following items:
32
33                     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
38                     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
46                     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
50                            commandPrefix oldName newName op
51
52                     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
67              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
75                     Ops indicates which operations are of interest, and is  a
76                     list of one or more of the following items:
77
78                     enter  Invoke  commandPrefix whenever the command name is
79                            executed, just before the actual  execution  takes
80                            place.
81
82                     leave  Invoke  commandPrefix whenever the command name is
83                            executed, just after the  actual  execution  takes
84                            place.
85
86                     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
99                     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
109                     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
113                     For enter and enterstep operations:
114
115                            commandPrefix command-string op
116
117                     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
128                     For leave and leavestep operations:
129
130                            commandPrefix command-string code result op
131
132                     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
145                     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
156                     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
163                     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
169                     The behavior of execution traces is  currently  undefined
170                     for a command name imported into another namespace.
171
172              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
185                     Ops  indicates which operations are of interest, and is a
186                     list of one or more of the following items:
187
188                     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
195                     read   Invoke  commandPrefix  whenever  the  variable  is
196                            read.
197
198                     write  Invoke  commandPrefix  whenever  the  variable  is
199                            written.
200
201                     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
209                     When  the trace triggers, three arguments are appended to
210                     commandPrefix so that the actual command is as follows:
211
212                            commandPrefix name1 name2 op
213
214                     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
229                     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
243                     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
260                     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
267                     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
278                     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
286                     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
293                     This command returns an empty string.
294
295       trace remove type name opList commandPrefix
296              Where type is either command, execution or variable.
297
298              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
305              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
312              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
318       trace info type name
319              Where type is either command, execution or variable.
320
321              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
330              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
339              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
347       For backwards compatibility, three other subcommands are available:
348
349              trace variable name ops command
350                     This  is  equivalent  to trace add variable name ops com‐
351                     mand.
352
353              trace vdelete name ops command
354                     This is equivalent to trace remove variable name ops com‐
355                     mand
356
357              trace vinfo name
358                     This is equivalent to trace info variable name
359
360       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

EXAMPLES

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
371              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
378       Ensure  that  the global variable foobar always contains the product of
379       the global variables foo and bar:
380
381              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
388       Print a trace of what commands are executed during the processing of  a
389       Tcl procedure:
390
391              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
397report y enterstep
398                  report z enterstep
399                  report {puts hello} enterstep
400                  hello
401

SEE ALSO

403       set(n), unset(n)
404

KEYWORDS

406       read, command, rename, variable, write, trace, unset
407
408
409
410Tcl                                   8.4                             trace(n)
Impressum