DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_CreateTrace(3)




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
                                                         contain-
                                                         ing com-
                                                         mand  to
                                                         be
                                                         traced
                                                         or
                                                         untraced.

     int level (in)                                      Only
                                                         commands
                                                         at    or
                                                         below
                                                         this
                                                         nesting
                                                         level
                                                         will  be
                                                         traced
                                                         unless 0
                                                         is
                                                         speci-
                                                         fied.  1
                                                         means
                                                         top-
                                                         level
                                                         commands
                                                         only,  2
                                                         means
                                                         top-
                                                         level
                                                         commands
                                                         or those
                                                         that are
                                                         invoked

Tcl                       Last change:                          1

Tcl_CreateTrace(3)   Tcl Library Procedures    Tcl_CreateTrace(3)

                                                         as
                                                         immedi-
                                                         ate
                                                         conse-
                                                         quences
                                                         of  exe-
                                                         cuting
                                                         top-
                                                         level
                                                         commands
                                                         (pro-
                                                         cedure
                                                         bodies,
                                                         brack-
                                                         eted
                                                         com-
                                                         mands,
                                                         etc.)
                                                         and   so
                                                         on.    A
                                                         value of
                                                         0  means
                                                         that
                                                         commands
                                                         at   any
                                                         level
                                                         are
                                                         traced.

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

     Tcl_CmdObjTraceProc *objProc (in)                   Procedure
                                                         to  call
                                                         for each
                                                         command
                                                         that  is
                                                         exe-
                                                         cuted.
                                                         See
                                                         below
                                                         for
                                                         details
                                                         of   the

Tcl                       Last change:                          2

Tcl_CreateTrace(3)   Tcl Library Procedures    Tcl_CreateTrace(3)

                                                         calling
                                                         sequence.

     Tcl_CmdTraceProc *proc (in)                         Procedure
                                                         to  call
                                                         for each
                                                         command
                                                         that  is
                                                         exe-
                                                         cuted.
                                                         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  per-
                                                         missible
                                                         and
                                                         results
                                                         in    no
                                                         callback
                                                         when the
                                                         trace is
                                                         deleted.

     Tcl_Trace trace (in)                                Token
                                                         for
                                                         trace to

Tcl                       Last change:                          3

Tcl_CreateTrace(3)   Tcl Library Procedures    Tcl_CreateTrace(3)

                                                         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 inter-
     preter 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.  Client-
     Data typically points to an application-specific data struc-
     ture 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  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  identi-
     fies  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  per-
     formed.

     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

Tcl                       Last change:                          4

Tcl_CreateTrace(3)   Tcl Library Procedures    Tcl_CreateTrace(3)

     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 parame-
     ter 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 gen-
     erating 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 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 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                       Last change:                          5

Tcl_CreateTrace(3)   Tcl Library Procedures    Tcl_CreateTrace(3)

     Tcl_CreateTrace is  an  alternative  interface  for  command
     tracing,  not  recommended for new applications.  It is pro-
     vided  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  parame-
     ter  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  pro-
     cedure  that  will be invoked; and cmdClientData, the client
     data that will be passed to the procedure.  The objc parame-
     ter 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
     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                       Last change:                          6


Man(1) output converted with man2html