diff options
Diffstat (limited to 'doc/trace.n')
| -rw-r--r-- | doc/trace.n | 41 |
1 files changed, 32 insertions, 9 deletions
diff --git a/doc/trace.n b/doc/trace.n index b81d275..377d257 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: trace.n,v 1.13.2.1 2003/10/08 17:51:07 dgp Exp $ +'\" RCS: @(#) $Id: trace.n,v 1.13.2.2 2004/10/27 14:43:14 dkf Exp $ '\" .so man.macros .TH trace n "8.4" Tcl "Tcl Built-In Commands" @@ -90,16 +90,16 @@ Invoke \fIcommand\fR whenever the command \fIname\fR is executed, just after the actual execution takes place. .TP \fBenterstep\fR -Invoke \fIcommand\fR for every tcl command which is executed +Invoke \fIcommand\fR for every Tcl command which is executed inside the procedure \fIname\fR, just before the actual execution takes place. For example if we have 'proc foo {} { puts "hello" }', -then a \fIenterstep\fR trace would be +then an \fIenterstep\fR trace would be invoked just before \fIputs "hello"\fR is executed. -Setting a \fIenterstep\fR trace on a \fIcommand\fR +Setting an \fIenterstep\fR trace on a \fIcommand\fR will not result in an error and is simply ignored. .TP \fBleavestep\fR -Invoke \fIcommand\fR for every tcl command which is executed +Invoke \fIcommand\fR for every Tcl command which is executed inside the procedure \fIname\fR, just after the actual execution takes place. Setting a \fIleavestep\fR trace on a \fIcommand\fR @@ -141,7 +141,7 @@ Note that the creation of many \fBenterstep\fR or \fBleavestep\fR traces can lead to unintuitive results, since the invoked commands from one trace can themselves lead to further command invocations for other traces. - +.PP \fICommand\fR executes in the same context as the code that invoked the traced operation: thus the \fIcommand\fR, if invoked from a procedure, will have access to the same local variables as code in the procedure. @@ -149,19 +149,19 @@ This context may be different than the context in which the trace was created. If \fIcommand\fR invokes a procedure (which it normally does) then the procedure will have to use upvar or uplevel commands if it wishes to access the local variables of the code which invoked the trace operation. - +.PP While \fIcommand\fR is executing during an execution trace, traces on \fIname\fR are temporarily disabled. This allows the \fIcommand\fR to execute \fIname\fR in its body without invoking any other traces again. If an error occurs while executing the \fIcommand\fR body, then the command \fIname\fR as a whole will return that same error. - +.PP When multiple traces are set on \fIname\fR, then for \fIenter\fR and \fIenterstep\fR operations, the traced commands are invoked in the reverse order of how the traces were originally created; and for \fIleave\fR and \fIleavestep\fR operations, the traced commands are invoked in the original order of creation. - +.PP The behavior of execution traces is currently undefined for a command \fIname\fR imported into another namespace. .RE @@ -354,6 +354,29 @@ future version of Tcl. They use an older syntax in which \fBarray\fR, \fBw\fR and \fBu\fR respectively, and the \fIops\fR argument is not a list, but simply a string concatenation of the operations, such as \fBrwua\fR. +.SH EXAMPLES +Print a message whenever either of the global variables \fBfoo\fR and +\fBbar\fR are updated, even if they have a different local name at the +time (which can be done with the \fBupvar\fR command): +.CS +proc tracer {varname args} { + upvar #0 $varname var + puts "$varname was updated to be \e"$var\e"" +} +\fBtrace add\fR variable foo write "tracer foo" +\fBtrace add\fR variable bar write "tracer bar" +.CE +.PP +Ensure that the global variable \fBfoobar\fR always contains the +product of the global variables \fBfoo\fR and \fBbar\fR: +.CS +proc doMult args { + global foo bar foobar + set foobar [expr {$foo * $bar}] +} +\fBtrace add\fR variable foo write doMult +\fBtrace add\fR variable bar write doMult +.CE .SH "SEE ALSO" set(n), unset(n) |