cmdtrace level | on ?noeval? ?notruncate?
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 characters, 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 evaluated
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 debugging.
fileid
This is a file id as returned by the open command. If
specified, then the trace output will be written to the
file rather than stdout. A stdio buffer flush is done
after every line is written so that the trace may be
monitored 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 evaluation:
command
A string containing the text of the command, before any
argument substitution.
argv
A list of the final argument information that will be
passed to the command after command, variable, and
backslash substitution.
evalLevel
The Tcl_Eval call level.
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
executed. The values of the errorInfo and errorCode variables
will be saved and restored on return from the command. 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 disabled. 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.
Category Command, a part of Tclx