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
15

DESCRIPTION

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
20       trace add type name ops ?args?
21              Where type is command, execution, or variable.
22
23              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
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 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
38                     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
46                     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
65              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
72                     Ops indicates which operations are of interest, and is  a
73                     list of one or more of the following items:
74
75                     enter  Invoke  command  whenever the command name is exe‐
76                            cuted, just  before  the  actual  execution  takes
77                            place.
78
79                     leave  Invoke  command  whenever the command name is exe‐
80                            cuted,  just  after  the  actual  execution  takes
81                            place.
82
83                     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
93                     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
100                     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
104                     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
117                     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
132                     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
142                     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
149                     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
155                     The  behavior  of execution traces is currently undefined
156                     for a command name imported into another namespace.
157
158              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
170                     Ops  indicates which operations are of interest, and is a
171                     list of one or more of the following items:
172
173                     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
180                     read   Invoke command whenever the variable is read.
181
182                     write  Invoke command whenever the variable is written.
183
184                     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
192                     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
210                     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
223                     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
239                     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
246                     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
257                     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
265                     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
272                     This command returns an empty string.
273
274       trace remove type name opList command
275              Where type is either command, execution or variable.
276
277              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
284              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
291              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
297       trace info type name
298              Where type is either command, execution or variable.
299
300              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
309              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
318              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
326       For backwards compatibility, three other subcommands are available:
327
328              trace variable name ops command
329                     This  is  equivalent  to trace add variable name ops com‐
330                     mand.
331
332              trace vdelete name ops command
333                     This is equivalent to trace remove variable name ops com‐
334                     mand
335
336              trace vinfo name
337                     This is equivalent to trace info variable name
338
339       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

EXAMPLES

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
356       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
365

SEE ALSO

367       set(n), unset(n)
368
369

KEYWORDS

371       read, command, rename, variable, write, trace, unset
372
373
374
375Tcl                                   8.4                             trace(n)
Impressum