cmdtrace level|on ?noeval? ?notruncate? ?procs? ?fileid?
?command cmd?
Print a trace statement for all commands executed
at depth of level or below (1 is the top level).
If on is specified, all commands at any level are
traced. The following options are available:
noeval Causes arguments to be printed unevaluated.
If noeval is specified, the arguments are
printed before evaluation. Otherwise, they
are printed afterwards.
If the command line is longer than 60 charac-
ters, it is truncated to 60 and a "..." is
postpended to indicate that there was more
output than was displayed. If an evaluated
argument contains a space, the entire argument
will be enclosed inside of braces (`{}') to
allow the reader to visually separate the
arguments from each other.
notruncate
Disables the truncation of commands and evalu-
ated arguments.
procs Enables the tracing of procedure calls only.
Commands that aren't procedure calls (i.e.
calls to commands that are written in C, C++
or some object-compatible language) are not
traced if the procs option is specified. This
option is particularly useful for greatly
reducing the output of cmdtrace while debug-
ging.
fileid This is a file id as returned by the open com-
mand. If specified, then the trace output
will be written to the file rather than std-
out. A stdio buffer flush is done after every
line is written so that the trace may be moni-
tored externally or provide useful information
for debugging problems that cause core dumps.
command cmd
Call the specified command cmd on when each
command is executed instead of tracing to a
file. See the description of the functionally
below. This option may not be specified with
a fileid.
The most common use of this command is to enable tracing
to a file during the development. If a failure occurs, a
trace is then available when needed. Command tracing will
slow down the execution of code, so it should be removed
when code is debugged. The following command will enable
tracing to a file for the remainder of the program:
cmdtrace on [open cmd.log w]
The command option causes a user specified trace command
to be called for each command executed. The command will
have the following arguments appended to it before evalua-
tion:
1) command -A string containing the text of the
command, before any argument substitution.
2) argv - A list of the final argument information
that will be passed to the command after command,
variable, and backslash substitution.
3) evalLevel - The Tcl_Eval call level.
4) procLevel - The procedure call level.
The command should be constructed in such a manner that it
will work if additional arguments are added in the future.
It is suggested that the command be a proc with the final
argument being args.
Tracing will be turned off while the command is being exe-
cuted. The values of the errorInfo and errorCode vari-
ables will be saved and restored on return from the com-
mand. It is the command's responsibility to preserve all
other state.
If an error occurs during the execution of command, an
error message is dumped to stderr and the tracing is dis-
abled. The underlying mechanism that this functionality
is built on does not support returning an error to the
interpreter.
cmdtrace off
Turn off all tracing.
cmdtrace depth
Returns the current maximum trace level, or zero if
trace is disabled.
This command is provided by Extended Tcl.