1Tcl_TraceVar(3)             Tcl Library Procedures             Tcl_TraceVar(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_TraceVar,  Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_Var‐
9       TraceInfo, Tcl_VarTraceInfo2 - monitor accesses to a variable
10

SYNOPSIS

12       #include <tcl.h>
13
14       int
15       Tcl_TraceVar(interp, varName, flags, proc, clientData)
16
17       int
18       Tcl_TraceVar2(interp, name1, name2, flags, proc, clientData)
19
20       Tcl_UntraceVar(interp, varName, flags, proc, clientData)
21
22       Tcl_UntraceVar2(interp, name1, name2, flags, proc, clientData)
23
24       ClientData
25       Tcl_VarTraceInfo(interp, varName, flags, proc, prevClientData)
26
27       ClientData
28       Tcl_VarTraceInfo2(interp, name1, name2, flags, proc, prevClientData)
29

ARGUMENTS

31       Tcl_Interp *interp (in)                       Interpreter    containing
32                                                     variable.
33
34       const char *varName (in)                      Name  of  variable.   May
35                                                     refer to a  scalar  vari‐
36                                                     able,  to  an array vari‐
37                                                     able with no index, or to
38                                                     an  array variable with a
39                                                     parenthesized index.
40
41       int flags (in)                                OR-ed combination of  the
42                                                     values   TCL_TRACE_READS,
43                                                     TCL_TRACE_WRITES,
44                                                     TCL_TRACE_UNSETS,
45                                                     TCL_TRACE_ARRAY,
46                                                     TCL_GLOBAL_ONLY,
47                                                     TCL_NAMESPACE_ONLY,
48                                                     TCL_TRACE_RESULT_DYNAMIC
49                                                     and
50                                                     TCL_TRACE_RESULT_OBJECT.
51                                                     Not all flags are used by
52                                                     all    procedures.    See
53                                                     below for  more  informa‐
54                                                     tion.
55
56       Tcl_VarTraceProc *proc (in)                   Procedure to invoke when‐
57                                                     ever one  of  the  traced
58                                                     operations occurs.
59
60       ClientData clientData (in)                    Arbitrary  one-word value
61                                                     to pass to proc.
62
63       const char *name1 (in)                        Name of scalar  or  array
64                                                     variable  (without  array
65                                                     index).
66
67       const char *name2 (in)                        For a trace on an element
68                                                     of  an  array,  gives the
69                                                     index  of  the   element.
70                                                     For   traces   on  scalar
71                                                     variables  or  on   whole
72                                                     arrays, is NULL.
73
74       ClientData prevClientData (in)                If  non-NULL,  gives last
75                                                     value     returned     by
76                                                     Tcl_VarTraceInfo       or
77                                                     Tcl_VarTraceInfo2,     so
78                                                     this   call  will  return
79                                                     information  about   next
80                                                     trace.    If  NULL,  this
81                                                     call will return informa‐
82                                                     tion about first trace.
83______________________________________________________________________________
84

DESCRIPTION

86       Tcl_TraceVar  allows  a  C procedure to monitor and control access to a
87       Tcl variable, so that the C procedure is invoked whenever the  variable
88       is read or written or unset.  If the trace is created successfully then
89       Tcl_TraceVar returns TCL_OK.  If an error occurred (e.g. varName speci‐
90       fies  an  element of an array, but the actual variable is not an array)
91       then TCL_ERROR is returned and an error message is left in  the  inter‐
92       preter's result.
93
94       The  flags  argument to Tcl_TraceVar indicates when the trace procedure
95       is to be invoked and provides information for setting up the trace.  It
96       consists of an OR-ed combination of any of the following values:
97
98       TCL_GLOBAL_ONLY
99              Normally, the variable will be looked up at the current level of
100              procedure call;  if this bit is set then the  variable  will  be
101              looked up at global level, ignoring any active procedures.
102
103       TCL_NAMESPACE_ONLY
104              Normally, the variable will be looked up at the current level of
105              procedure call;  if this bit is set then the  variable  will  be
106              looked  up  in the current namespace, ignoring any active proce‐
107              dures.
108
109       TCL_TRACE_READS
110              Invoke proc whenever an attempt is made to read the variable.
111
112       TCL_TRACE_WRITES
113              Invoke proc whenever an attempt is made to modify the variable.
114
115       TCL_TRACE_UNSETS
116              Invoke proc whenever the variable is unset.  A variable  may  be
117              unset  either explicitly by an unset command, or implicitly when
118              a procedure  returns  (its  local  variables  are  automatically
119              unset)  or  when  the  interpreter is deleted (all variables are
120              automatically unset).
121
122       TCL_TRACE_ARRAY
123              Invoke proc whenever the array command is invoked.   This  gives
124              the  trace  procedure  a chance to update the array before array
125              names or array get is called.  Note that this is  called  before
126              an array set, but that will trigger write traces.
127
128       TCL_TRACE_RESULT_DYNAMIC
129              The  result  of  invoking  the  proc  is a dynamically allocated
130              string that will be released by the Tcl library via  a  call  to
131              ckfree.    Must   not   be   specified   at  the  same  time  as
132              TCL_TRACE_RESULT_OBJECT.
133
134       TCL_TRACE_RESULT_OBJECT
135              The result of invoking the proc is a Tcl_Obj* (cast to a  char*)
136              with  a  reference count of at least one.  The ownership of that
137              reference will be transferred to the Tcl core for release  (when
138              the  core  has finished with it) via a call to Tcl_DecrRefCount.
139              Must   not    be    specified    at    the    same    time    as
140              TCL_TRACE_RESULT_DYNAMIC.
141
142       Whenever  one  of the specified operations occurs on the variable, proc
143       will be invoked.  It should have arguments and result  that  match  the
144       type Tcl_VarTraceProc:
145
146              typedef char *Tcl_VarTraceProc(
147                      ClientData clientData,
148                      Tcl_Interp *interp,
149                      char *name1,
150                      char *name2,
151                      int flags);
152
153       The clientData and interp parameters will have the same values as those
154       passed to Tcl_TraceVar when the trace was  created.   ClientData  typi‐
155       cally  points  to an application-specific data structure that describes
156       what to do when proc is invoked.  Name1 and name2 give the name of  the
157       traced  variable  in  the  normal two-part form (see the description of
158       Tcl_TraceVar2 below for details).  Flags is  an  OR-ed  combination  of
159       bits  providing  several  pieces  of  information.   One  of  the  bits
160       TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_ARRAY, or TCL_TRACE_UNSETS
161       will  be set in flags to indicate which operation is being performed on
162       the variable.  The bit TCL_GLOBAL_ONLY will be set whenever  the  vari‐
163       able  being  accessed  is  a global one not accessible from the current
164       level of procedure call:  the trace procedure will need  to  pass  this
165       flag back to variable-related procedures like Tcl_GetVar if it attempts
166       to access the variable.  The bit TCL_NAMESPACE_ONLY will be  set  when‐
167       ever the variable being accessed is a namespace one not accessible from
168       the current level of procedure call:  the trace procedure will need  to
169       pass  this  flag back to variable-related procedures like Tcl_GetVar if
170       it attempts to access the variable.  The bit  TCL_TRACE_DESTROYED  will
171       be  set  in flags if the trace is about to be destroyed;  this informa‐
172       tion may be useful to proc so that it can clean  up  its  own  internal
173       data  structures  (see  the  section TCL_TRACE_DESTROYED below for more
174       details).  Lastly, the bit TCL_INTERP_DESTROYED  will  be  set  if  the
175       entire interpreter is being destroyed.  When this bit is set, proc must
176       be  especially  careful  in  the  things  it  does  (see  the   section
177       TCL_INTERP_DESTROYED below).  The trace procedure's return value should
178       normally be NULL;  see ERROR RETURNS below  for  information  on  other
179       possibilities.
180
181       Tcl_UntraceVar  may  be used to remove a trace.  If the variable speci‐
182       fied by interp, varName, and flags has a trace set  with  flags,  proc,
183       and  clientData,  then  the corresponding trace is removed.  If no such
184       trace exists, then the call to Tcl_UntraceVar has no effect.  The  same
185       bits are valid for flags as for calls to Tcl_TraceVar.
186
187       Tcl_VarTraceInfo  may  be used to retrieve information about traces set
188       on a given variable.  The return value  from  Tcl_VarTraceInfo  is  the
189       clientData  associated  with  a particular trace.  The trace must be on
190       the variable specified by the  interp,  varName,  and  flags  arguments
191       (only  the  TCL_GLOBAL_ONLY  and  TCL_NAMESPACE_ONLY bits from flags is
192       used;  other bits are ignored) and its trace procedure must the same as
193       the  proc  argument.   If  the prevClientData argument is NULL then the
194       return value corresponds to the first (most recently created)  matching
195       trace,  or NULL if there are no matching traces.  If the prevClientData
196       argument is not NULL, then it should be the return value from a  previ‐
197       ous  call to Tcl_VarTraceInfo.  In this case, the new return value will
198       correspond to the next matching trace after the  one  whose  clientData
199       matches  prevClientData,  or NULL if no trace matches prevClientData or
200       if there are no more matching traces after it.  This mechanism makes it
201       possible  to  step  through all of the traces for a given variable that
202       have the same proc.
203

TWO-PART NAMES

205       The procedures Tcl_TraceVar2,  Tcl_UntraceVar2,  and  Tcl_VarTraceInfo2
206       are  identical  to  Tcl_TraceVar, Tcl_UntraceVar, and Tcl_VarTraceInfo,
207       respectively, except that the name of  the  variable  consists  of  two
208       parts.   Name1  gives the name of a scalar variable or array, and name2
209       gives the name of an element within an  array.   When  name2  is  NULL,
210       name1  may  contain both an array and an element name: if the name con‐
211       tains an open parenthesis and ends with a close parenthesis,  then  the
212       value  between the parentheses is treated as an element name (which can
213       have any string value) and the characters before the first open  paren‐
214       thesis  are treated as the name of an array variable.  If name2 is NULL
215       and name1 does not refer to an array element it means that  either  the
216       variable  is  a  scalar  or  the trace is to be set on the entire array
217       rather than an individual element (see  WHOLE-ARRAY  TRACES  below  for
218       more information).
219

ACCESSING VARIABLES DURING TRACES

221       During  read,  write,  and  array traces, the trace procedure can read,
222       write, or unset the traced variable using Tcl_GetVar2, Tcl_SetVar2, and
223       other procedures.  While proc is executing, traces are temporarily dis‐
224       abled for the variable, so that calls to  Tcl_GetVar2  and  Tcl_SetVar2
225       will  not  cause  proc  or  other trace procedures to be invoked again.
226       Disabling only occurs for the variable whose trace procedure is active;
227       accesses  to other variables will still be traced.  However, if a vari‐
228       able is unset during a read or write trace then unset  traces  will  be
229       invoked.
230
231       During  unset traces the variable has already been completely expunged.
232       It is possible for the trace procedure to read or write  the  variable,
233       but  this  will  be a new version of the variable.  Traces are not dis‐
234       abled during unset traces as they are for read and  write  traces,  but
235       existing  traces  have  been removed from the variable before any trace
236       procedures are invoked.  If new traces are set by  unset  trace  proce‐
237       dures,  these traces will be invoked on accesses to the variable by the
238       trace procedures.
239

CALLBACK TIMING

241       When read tracing has been specified for a variable, the  trace  proce‐
242       dure  will  be  invoked  whenever  the  variable's value is read.  This
243       includes set Tcl commands, $-notation in Tcl commands, and  invocations
244       of  the  Tcl_GetVar  and  Tcl_GetVar2 procedures.  Proc is invoked just
245       before the variable's value is returned.  It may modify  the  value  of
246       the  variable  to  affect what is returned by the traced access.  If it
247       unsets the variable then the access will return an error just as if the
248       variable never existed.
249
250       When  write tracing has been specified for a variable, the trace proce‐
251       dure will be invoked whenever the variable's value is  modified.   This
252       includes  set  commands, commands that modify variables as side effects
253       (such as catch and scan), and calls to the Tcl_SetVar  and  Tcl_SetVar2
254       procedures).   Proc will be invoked after the variable's value has been
255       modified, but before the new value of the variable has  been  returned.
256       It  may  modify the value of the variable to override the change and to
257       determine the value actually returned by  the  traced  access.   If  it
258       deletes  the  variable  then  the  traced  access  will return an empty
259       string.
260
261       When array tracing has been specified,  the  trace  procedure  will  be
262       invoked  at  the  beginning of the array command implementation, before
263       any of the operations like get, set, or names have been  invoked.   The
264       trace  procedure  can  modify  the  array  elements with Tcl_SetVar and
265       Tcl_SetVar2.
266
267       When unset tracing has been specified,  the  trace  procedure  will  be
268       invoked  whenever the variable is destroyed.  The traces will be called
269       after the variable has been completely unset.
270

WHOLE-ARRAY TRACES

272       If a call to Tcl_TraceVar or Tcl_TraceVar2 specifies  the  name  of  an
273       array  variable without an index into the array, then the trace will be
274       set on the array as a whole.  This means  that  proc  will  be  invoked
275       whenever  any element of the array is accessed in the ways specified by
276       flags.  When an array is unset, a whole-array  trace  will  be  invoked
277       just  once,  with  name1 equal to the name of the array and name2 NULL;
278       it will not be invoked once for each element.
279

MULTIPLE TRACES

281       It is possible for multiple traces to exist on the same variable.  When
282       this  happens,  all  of  the  trace  procedures will be invoked on each
283       access, in order from most-recently-created to  least-recently-created.
284       When  there  exist whole-array traces for an array as well as traces on
285       individual elements, the whole-array  traces  are  invoked  before  the
286       individual-element  traces.   If a read or write trace unsets the vari‐
287       able then all of the unset traces will be invoked but the remainder  of
288       the read and write traces will be skipped.
289

ERROR RETURNS

291       Under normal conditions trace procedures should return NULL, indicating
292       successful completion.  If proc returns a non-NULL value  it  signifies
293       that an error occurred.  The return value must be a pointer to a static
294       character string containing an error message, unless (exactly  one  of)
295       the  TCL_TRACE_RESULT_DYNAMIC and TCL_TRACE_RESULT_OBJECT flags is set,
296       which specify that the  result  is  either  a  dynamic  string  (to  be
297       released  with  ckfree) or a Tcl_Obj* (cast to char* and to be released
298       with Tcl_DecrRefCount) containing the error message.  If a trace proce‐
299       dure returns an error, no further traces are invoked for the access and
300       the traced access aborts with the given message.  Trace procedures  can
301       use  this  facility  to make variables read-only, for example (but note
302       that the value of the variable will already have been  modified  before
303       the  trace  procedure  is  called,  so the trace procedure will have to
304       restore the correct value).
305
306       The return value from proc is only used during read and write  tracing.
307       During unset traces, the return value is ignored and all relevant trace
308       procedures will always be invoked.
309

RESTRICTIONS

311       A trace procedure can be called at any time, even when there is a  par‐
312       tially  formed  result  in the interpreter's result area.  If the trace
313       procedure does anything that could damage this result (such as  calling
314       Tcl_Eval)  then  it  must save the original values of the interpreter's
315       result and freeProc fields and restore them before it returns.
316

UNDEFINED VARIABLES

318       It is legal to set a trace on an undefined variable.  The variable will
319       still appear to be undefined until the first time its value is set.  If
320       an undefined variable is traced and then unset,  the  unset  will  fail
321       with  an error (“no such variable”), but the trace procedure will still
322       be invoked.
323

TCL_TRACE_DESTROYED FLAG

325       In an unset callback to proc, the TCL_TRACE_DESTROYED  bit  is  set  in
326       flags if the trace is being removed as part of the deletion.  Traces on
327       a variable are always removed whenever the variable  is  deleted;   the
328       only  time  TCL_TRACE_DESTROYED  is  not set is for a whole-array trace
329       invoked when only a single element of an array is unset.
330

TCL_INTERP_DESTROYED

332       When an interpreter is destroyed, unset traces are called  for  all  of
333       its  variables.   The TCL_INTERP_DESTROYED bit will be set in the flags
334       argument passed to the trace  procedures.   Trace  procedures  must  be
335       extremely  careful  in  what they do if the TCL_INTERP_DESTROYED bit is
336       set.  It is not safe for the procedures to invoke any Tcl procedures on
337       the  interpreter, since its state is partially deleted.  All that trace
338       procedures should do under these circumstances is to clean up and  free
339       their own internal data structures.
340

BUGS

342       Tcl  does  not  do  any error checking to prevent trace procedures from
343       misusing the interpreter during traces with TCL_INTERP_DESTROYED set.
344
345       Array traces are not yet integrated with the Tcl info  exists  command,
346       nor is there Tcl-level access to array traces.
347

SEE ALSO

349       trace(n)
350

KEYWORDS

352       clientData, trace, variable
353
354
355
356Tcl                                   7.4                      Tcl_TraceVar(3)
Impressum