       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 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.
