DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_CreateTrace(3)




______________________________________________________________________________


NAME

       Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for com-
       mand 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 con-
                                                              taining  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 imme-
                                                              diate     conse-
                                                              quences of  exe-
                                                              cuting top-level
                                                              commands (proce-
                                                              dure     bodies,
                                                              bracketed   com-
                                                              mands, etc.) and
                                                              so on.  A  value
                                                              of  0 means that
                                                              commands at  any
                                                              level        are
                                                              traced.

       int                         flags            (in)      Flags  governing
                                                              the trace execu-
                                                              tion.  See below
                                                              for details.

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

       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 objProc
                                                              or proc.

       Tcl_CmdObjTraceDeleteProc   *deleteProc                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_Cre-
                                                              ateTrace).
_________________________________________________________________


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  applica-
       tion, 2 for the next-level commands passed to Tcl_Eval as part of pars-
       ing or interpreting level-1 commands, and so on). The command parameter
       points to a string containing the text of the command, before any argu-
       ment 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_GetCommandTokenInfo, or Tcl_SetCommandTokenInfo
       to  manipulate the definition of the command. The objc and objv parame-
       ters 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  inter-
       preter 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_Create-
       Trace).

       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 parame-
       ter 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 per-
       formance will be improved significantly.  (This functionality is desir-
       able, for example, when using Tcl_CreateObjTrace to implement an execu-
       tion 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 substitu-
       tions.  If there is a syntax error in a command, or if there is no com-
       mand procedure associated with a command name,  then  no  tracing  will
       occur for that command.  If a string passed to Tcl_Eval contains multi-
       ple 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 compati-
       bility 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_Cmd-
       TraceProc:
              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 cmd-
       ClientData, the client data that will be passed to the procedure.   The
       objc parameter is replaced with an argv parameter, that gives the argu-
       ments 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 compila-
       tion 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_Create-
       Trace  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                                                         Tcl_CreateTrace(3)

Man(1) output converted with man2html