1Tcl_CreateTrace(3)          Tcl Library Procedures          Tcl_CreateTrace(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for com‐
9       mand execution to be traced
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Trace
15       Tcl_CreateTrace(interp, level, proc, clientData)
16
17       Tcl_Trace
18       Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)
19
20       Tcl_DeleteTrace(interp, trace)
21

ARGUMENTS

23       Tcl_Interp *interp (in)                             Interpreter    con‐
24                                                           taining  command to
25                                                           be    traced     or
26                                                           untraced.
27
28       int level (in)                                      Only commands at or
29                                                           below this  nesting
30                                                           level    will    be
31                                                           traced unless 0  is
32                                                           specified.  1 means
33                                                           top-level  commands
34                                                           only,  2 means top-
35                                                           level  commands  or
36                                                           those    that   are
37                                                           invoked as  immedi‐
38                                                           ate consequences of
39                                                           executing top-level
40                                                           commands (procedure
41                                                           bodies,   bracketed
42                                                           commands, etc.) and
43                                                           so on.  A value  of
44                                                           0  means  that com‐
45                                                           mands at any  level
46                                                           are traced.
47
48       int flags (in)                                      Flags governing the
49                                                           trace    execution.
50                                                           See    below    for
51                                                           details.
52
53       Tcl_CmdObjTraceProc *objProc (in)                   Procedure  to  call
54                                                           for   each  command
55                                                           that  is  executed.
56                                                           See    below    for
57                                                           details   of    the
58                                                           calling sequence.
59
60       Tcl_CmdTraceProc *proc (in)                         Procedure  to  call
61                                                           for  each   command
62                                                           that  is  executed.
63                                                           See    below    for
64                                                           details    on   the
65                                                           calling sequence.
66
67       ClientData clientData (in)                          Arbitrary  one-word
68                                                           value  to  pass  to
69                                                           objProc or proc.
70
71       Tcl_CmdObjTraceDeleteProc *deleteProc (in)          Procedure  to  call
72                                                           when  the  trace is
73                                                           deleted.  See below
74                                                           for  details of the
75                                                           calling   sequence.
76                                                           A  NULL  pointer is
77                                                           permissible     and
78                                                           results in no call‐
79                                                           back when the trace
80                                                           is deleted.
81
82       Tcl_Trace trace (in)                                Token  for trace to
83                                                           be removed  (return
84                                                           value from previous
85                                                           call to Tcl_Create‐
86                                                           Trace).
87_________________________________________________________________
88

DESCRIPTION

90       Tcl_CreateObjTrace  arranges  for command tracing.  After it is called,
91       objProc will be invoked before the Tcl interpreter  calls  any  command
92       procedure  when  evaluating  commands in interp.  The return value from
93       Tcl_CreateObjTrace is a token for the trace, which  may  be  passed  to
94       Tcl_DeleteTrace  to  remove  the  trace.   There  may be many traces in
95       effect simultaneously for the same interpreter.
96
97       objProc  should  have  arguments  and  result  that  match  the   type,
98       Tcl_CmdObjTraceProc:
99              typedef int Tcl_CmdObjTraceProc(
100                      ClientData clientData,
101                      Tcl_Interp* interp,
102                      int level,
103                      const char *command,
104                      Tcl_Command commandToken,
105                      int objc,
106                      Tcl_Obj *const objv[] );
107       The  clientData  and  interp parameters are copies of the corresponding
108       arguments given to Tcl_CreateTrace.  ClientData typically points to  an
109       application-specific  data  structure  that  describes  what to do when
110       objProc is invoked.  The level parameter gives the nesting level of the
111       command  (1  for  top-level commands passed to Tcl_Eval by the applica‐
112       tion, 2 for the next-level commands passed to Tcl_Eval as part of pars‐
113       ing or interpreting level-1 commands, and so on). The command parameter
114       points to a string containing the text of the command, before any argu‐
115       ment  substitution.   The commandToken parameter is a Tcl command token
116       that identifies the command to be invoked.  The token may be passed  to
117       Tcl_GetCommandName,  Tcl_GetCommandInfoFromToken,  or Tcl_SetCommandIn‐
118       foFromToken to manipulate the definition of the command. The  objc  and
119       objv  parameters designate the final parameter count and parameter vec‐
120       tor that will be passed to the command, and have had all  substitutions
121       performed.
122
123       The objProc callback is expected to return a standard Tcl status return
124       code.  If this code is TCL_OK (the normal case), then  the  Tcl  inter‐
125       preter will invoke the command.  Any other return code is treated as if
126       the command returned that status, and the command is not invoked.
127
128       The objProc callback must not modify objv in any way.  It is,  however,
129       permissible  to  change  the command by calling Tcl_SetCommandTokenInfo
130       prior to returning.  Any such change takes effect immediately, and  the
131       command is invoked with the new information.
132
133       Tracing  will  only  occur  for  commands at nesting level less than or
134       equal to the level parameter (i.e. the level parameter to objProc  will
135       always  be  less  than  or  equal to the level parameter to Tcl_Create‐
136       Trace).
137
138       Tracing has a significant effect  on  runtime  performance  because  it
139       causes  the  bytecode  compiler to refrain from generating in-line code
140       for Tcl commands such as if and while in order that they may be traced.
141       If traces for the built-in commands are not required, the flags parame‐
142       ter may be set to the constant value TCL_ALLOW_INLINE_COMPILATION.   In
143       this  case,  traces on built-in commands may or may not result in trace
144       callbacks, depending on the state of the interpreter, but run-time per‐
145       formance will be improved significantly.  (This functionality is desir‐
146       able, for example, when using Tcl_CreateObjTrace to implement an execu‐
147       tion time profiler.)
148
149       Calls  to  objProc will be made by the Tcl parser immediately before it
150       calls the command procedure for the  command  (cmdProc).   This  occurs
151       after  argument  parsing  and  substitution, so tracing for substituted
152       commands occurs before tracing of the commands containing the substitu‐
153       tions.  If there is a syntax error in a command, or if there is no com‐
154       mand procedure associated with a command name,  then  no  tracing  will
155       occur for that command.  If a string passed to Tcl_Eval contains multi‐
156       ple commands (bracketed, or on different lines) then multiple calls  to
157       objProc will occur, one for each command.
158
159       Tcl_DeleteTrace  removes  a trace, so that no future calls will be made
160       to the procedure associated  with  the  trace.   After  Tcl_DeleteTrace
161       returns, the caller should never again use the trace token.
162
163       When  Tcl_DeleteTrace is called, the interpreter invokes the deleteProc
164       that was passed as a parameter to Tcl_CreateObjTrace.   The  deleteProc
165       must match the type, Tcl_CmdObjTraceDeleteProc:
166              typedef void Tcl_CmdObjTraceDeleteProc(
167                      ClientData clientData);
168       The  clientData  parameter will be the same as the clientData parameter
169       that was originally passed to Tcl_CreateObjTrace.
170
171       Tcl_CreateTrace is an alternative interface for  command  tracing,  not
172       recommended for new applications.  It is provided for backward compati‐
173       bility with code that was developed  for  older  versions  of  the  Tcl
174       interpreter.  It is similar to Tcl_CreateObjTrace, except that its proc
175       parameter should have arguments and result that match the type Tcl_Cmd‐
176       TraceProc:
177              typedef void Tcl_CmdTraceProc(
178                      ClientData clientData,
179                      Tcl_Interp *interp,
180                      int level,
181                      char *command,
182                      Tcl_CmdProc *cmdProc,
183                      ClientData cmdClientData,
184                      int argc,
185                      const char *argv[]);
186       The parameters to the proc callback are similar to those of the objProc
187       callback above. The commandToken is replaced with cmdProc, a pointer to
188       the  (string-based)  command  procedure  that will be invoked; and cmd‐
189       ClientData, the client data that will be passed to the procedure.   The
190       objc parameter is replaced with an argv parameter, that gives the argu‐
191       ments to the command as character strings.  Proc must  not  modify  the
192       command or argv strings.
193
194       If  a  trace created with Tcl_CreateTrace is in effect, inline compila‐
195       tion of Tcl commands such as if and while is always disabled.  There is
196       no  notification  when a trace created with Tcl_CreateTrace is deleted.
197       There is no way to be notified when the trace  created  by  Tcl_Create‐
198       Trace  is deleted.  There is no way for the proc associated with a call
199       to Tcl_CreateTrace to abort execution of command.
200

KEYWORDS

202       command, create, delete, interpreter, trace
203
204
205
206Tcl                                                         Tcl_CreateTrace(3)
Impressum