tcl7.6 C API - CrtTrace






NAME

     Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command  exe-
     cution to be traced


SYNOPSIS

     #include <tcl.h>

     Tcl_Trace
     Tcl_CreateTrace(interp, level, proc, clientData)

     Tcl_DeleteTrace(interp, trace)


ARGUMENTS

     Tcl_Interp         *interp          (in)      Interpreter
                                                   containing
                                                   command to  be
                                                   traced      or
                                                   untraced.

     int                level            (in)      Only  commands
                                                   at   or  below
                                                   this   nesting
                                                   level  will be
                                                   traced.      1
                                                   means     top-
                                                   level commands
                                                   only,  2 means
                                                   top-level com-
                                                   mands or those
                                                   that       are
                                                   invoked     as
                                                   immediate
                                                   consequences
                                                   of   executing
                                                   top-level com-
                                                   mands    (pro-
                                                   cedure bodies,
                                                   bracketed com-
                                                   mands,   etc.)
                                                   and so on.

     Tcl_CmdTraceProc   *proc            (in)      Procedure   to
                                                   call  for each
                                                   command that's
                                                   executed.  See
                                                   below      for
                                                   details on the
                                                   calling
                                                   sequence.

     ClientData         clientData       (in)      Arbitrary
                                                   one-word value
                                                   to   pass   to
                                                   proc.

     Tcl_Trace          trace            (in)      Token      for
                                                   trace   to  be
                                                   removed
                                                   (return  value
                                                   from  previous
                                                   call        to
                                                   Tcl_CreateTrace).





DESCRIPTION

     Tcl_CreateTrace arranges for command tracing.  From now  on,
     proc  will be invoked before Tcl calls command procedures to
     process  commands  in  interp.   The   return   value   from
     Tcl_CreateTrace  is  a  token  for  the  trace, which may be
     passed to Tcl_DeleteTrace to remove the trace.  There may be
     many  traces  in  effect simultaneously for the same command
     interpreter.

     Proc should have arguments and result that  match  the  type
     Tcl_CmdTraceProc:
          typedef void Tcl_CmdTraceProc(
            ClientData clientData,
            Tcl_Interp *interp,
            int level,
            char *command,
            Tcl_CmdProc *cmdProc,
            ClientData cmdClientData,
            int argc,
            char *argv[]);
     The clientData and  interp  parameters  are  copies  of  the
     corresponding  arguments  given to Tcl_CreateTrace.  Client-
     Data typically points to an application-specific data struc-
     ture  that describes what to do when proc is invoked.  Level
     gives the nesting level of the command (1 for top-level com-
     mands  passed  to  Tcl_Eval  by  the  application, 2 for the
     next-level commands passed to Tcl_Eval as part of parsing or
     interpreting  level-1  commands, and so on).  Command points
     to a string containing the text of the command,  before  any
     argument  substitution.  CmdProc contains the address of the
     command procedure that will be called to process the command
     (i.e.   the   proc   argument   of  some  previous  call  to
     Tcl_CreateCommand) and cmdClientData contains the associated
     client  data  for  cmdProc  (the  clientData value passed to
     Tcl_CreateCommand).  Argc and argv give the  final  argument
     information  that  will be passed to cmdProc, after command,
     variable, and backslash substitution.  Proc must not  modify
     the command or argv strings.

     Tracing will only occur for commands at nesting  level  less
     than or equal to the level parameter (i.e. the level parame-
     ter to proc will always be less than or equal to  the  level
     parameter to Tcl_CreateTrace).

     Calls to proc will be made by  the  Tcl  parser  immediately
     before  it  calls  the  command  procedure  for  the command
     (cmdProc).  This occurs after argument parsing and substitu-
     tion,  so  tracing  for  substituted  commands occurs before
     tracing of the commands containing  the  substitutions.   If
     there is a syntax error in a command, or if there is no com-
     mand procedure associated with a command name, then no trac-
     ing  will  occur  for  that  command.  If a string passed to
     Tcl_Eval contains multiple commands (bracketed, or  on  dif-
     ferent  lines)  then  multiple calls to proc will occur, one
     for each command.  The command  string  for  each  of  these
     trace  calls  will  reflect  only  a single command, not the
     entire string passed to Tcl_Eval.

     Tcl_DeleteTrace removes a trace, so  that  no  future  calls
     will  be  made  to  the procedure associated with the trace.
     After Tcl_DeleteTrace returns, the caller should never again
     use the trace token.



KEYWORDS

     command, create, delete, interpreter, trace