Provided by: tcl8.5-doc_8.5.19-4_all bug

NAME

       Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for command execution to be traced

SYNOPSIS

       #include <tcl.h>

       Tcl_Trace
       Tcl_CreateTrace(interp, level, proc, clientData)

       Tcl_Trace
       Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)

       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  unless  0  is  specified.   1 means top-level
                                                           commands only, 2 means top-level  commands  or  those
                                                           that   are   invoked  as  immediate  consequences  of
                                                           executing  top-level  commands   (procedure   bodies,
                                                           bracketed  commands,  etc.)  and so on.  A value of 0
                                                           means that commands at any level are traced.

       int flags (in)                                      Flags governing the trace execution.  See  below  for
                                                           details.

       Tcl_CmdObjTraceProc *objProc (in)                   Procedure  to call for each command that is executed.
                                                           See below for details of the calling sequence.

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

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

       Tcl_CmdObjTraceDeleteProc *deleteProc (in)          Procedure  to  call  when  the trace is deleted.  See
                                                           below for details of the calling  sequence.   A  NULL
                                                           pointer  is  permissible  and  results in no callback
                                                           when the trace is deleted.

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

DESCRIPTION

       Tcl_CreateObjTrace  arranges for command tracing.  After it is called, objProc will be invoked before the
       Tcl interpreter calls any command procedure when evaluating commands in interp.  The  return  value  from
       Tcl_CreateObjTrace  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 interpreter.

       objProc should have arguments and result that match the type, Tcl_CmdObjTraceProc:
              typedef int Tcl_CmdObjTraceProc(
                      ClientData clientData,
                      Tcl_Interp* interp,
                      int level,
                      const char *command,
                      Tcl_Command commandToken,
                      int objc,
                      Tcl_Obj *const objv[] );
       The clientData and interp parameters are copies of the corresponding arguments given to  Tcl_CreateTrace.
       ClientData  typically  points  to  an  application-specific data structure that describes what to do when
       objProc is invoked.  The level parameter gives the nesting level of the command (1 for top-level commands
       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). The command parameter points to a string containing
       the  text  of the command, before any argument substitution.  The commandToken parameter is a Tcl command
       token that identifies the command to  be  invoked.   The  token  may  be  passed  to  Tcl_GetCommandName,
       Tcl_GetCommandInfoFromToken,  or Tcl_SetCommandInfoFromToken to manipulate the definition of the command.
       The objc and objv parameters designate the final parameter count and parameter vector that will be passed
       to the command, and have had all substitutions performed.

       The  objProc  callback  is  expected to return a standard Tcl status return code.  If this code is TCL_OK
       (the normal case), then the Tcl interpreter will invoke the command.  Any other return code is treated as
       if the command returned that status, and the command is not invoked.

       The  objProc callback must not modify objv in any way.  It is, however, permissible to change the command
       by calling Tcl_SetCommandTokenInfo prior to returning.  Any such change takes effect immediately, and the
       command is invoked with the new information.

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

       Tracing has a significant effect on runtime performance  because  it  causes  the  bytecode  compiler  to
       refrain  from  generating  in-line  code  for Tcl commands such as if and while in order that they may be
       traced.  If traces for the built-in commands are not required, the flags parameter  may  be  set  to  the
       constant  value  TCL_ALLOW_INLINE_COMPILATION.   In this case, traces on built-in commands may or may not
       result in trace callbacks, depending on the state of the interpreter, but run-time  performance  will  be
       improved  significantly.  (This functionality is desirable, for example, when using Tcl_CreateObjTrace to
       implement an execution time profiler.)

       Calls to objProc will be made by the Tcl parser immediately before it calls the command procedure for the
       command  (cmdProc).   This  occurs  after  argument  parsing and substitution, 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 command procedure associated with a command name, then no tracing will
       occur for that command.  If a string passed to Tcl_Eval contains  multiple  commands  (bracketed,  or  on
       different lines) then multiple calls to objProc will occur, one for each command.

       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.

       When Tcl_DeleteTrace is called, the interpreter invokes the deleteProc that was passed as a parameter  to
       Tcl_CreateObjTrace.  The deleteProc must match the type, Tcl_CmdObjTraceDeleteProc:
              typedef void Tcl_CmdObjTraceDeleteProc(
                      ClientData clientData);
       The  clientData  parameter  will  be  the  same as the clientData parameter that was originally passed to
       Tcl_CreateObjTrace.

       Tcl_CreateTrace is an alternative interface for command tracing, not recommended  for  new  applications.
       It  is  provided  for  backward  compatibility with code that was developed for older versions of the Tcl
       interpreter.  It is similar to Tcl_CreateObjTrace, except that its proc parameter 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,
                      const char *argv[]);
       The  parameters to the proc callback are similar to those of the objProc callback above. The commandToken
       is replaced with cmdProc, a pointer to the (string-based) command procedure that  will  be  invoked;  and
       cmdClientData, the client data that will be passed to the procedure.  The objc parameter is replaced with
       an argv parameter, that gives the arguments to the command as character strings.  Proc  must  not  modify
       the command or argv strings.

       If  a  trace created with Tcl_CreateTrace is in effect, inline compilation of Tcl commands such as if and
       while is always disabled.  There is no notification when a trace created with Tcl_CreateTrace is deleted.
       There is no way to be notified when the trace created by Tcl_CreateTrace is deleted.  There is no way for
       the proc associated with a call to Tcl_CreateTrace to abort execution of command.

KEYWORDS

       command, create, delete, interpreter, trace