This command is part of the
TclX package.
-
- cmdtrace [level | on] options...
-
- cmdtrace off
-
- cmdtrace depth
See also the
trace command's execution traces.
-
- 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 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 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.
