2. EL 6 ELS
  3. tcl
  4. Tcl_DeleteTrace(3)

Scroll to navigation

Tcl_CreateTrace(3) Tcl Library Procedures Tcl_CreateTrace(3) 





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







  

    
    Tcl