1Tcl_CreateTrace(3) Tcl Library Procedures Tcl_CreateTrace(3)
2______________________________________________________________________________
6
8 Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for com‐
9 mand execution to be traced
10
12 #include <tcl.h>
13 Tcl_Trace
15 Tcl_CreateTrace(interp, level, proc, clientData)
16 Tcl_Trace
18 Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)
19 Tcl_DeleteTrace(interp, trace)
21
23 Tcl_Interp *interp (in) Interpreter con‐
24 taining command to
25 be traced or un‐
26 traced.
27 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 in‐
37 voked as immediate
38 consequences of ex‐
39 ecuting 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 int flags (in) Flags governing the
49 trace execution.
50 See below for de‐
51 tails.
52 Tcl_CmdObjTraceProc *objProc (in) Procedure to call
54 for each command
55 that is executed.
56 See below for de‐
57 tails of the call‐
58 ing sequence.
59 Tcl_CmdTraceProc *proc (in) Procedure to call
61 for each command
62 that is executed.
63 See below for de‐
64 tails on the call‐
65 ing sequence.
66 ClientData clientData (in) Arbitrary one-word
68 value to pass to
69 objProc or proc.
70 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 re‐
78 sults in no call‐
79 back when the trace
80 is deleted.
81 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
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 ef‐
95 fect simultaneously for the same interpreter.
96 objProc should have arguments and result that match the type, Tcl_Cm‐
98 dObjTraceProc:
99 typedef int Tcl_CmdObjTraceProc(
101 ClientData clientData,
102 Tcl_Interp* interp,
103 int level,
104 const char *command,
105 Tcl_Command commandToken,
106 int objc,
107 Tcl_Obj *const objv[]);
108 The clientData and interp parameters are copies of the corresponding
110 arguments given to Tcl_CreateTrace. ClientData typically points to an
111 application-specific data structure that describes what to do when ob‐
112 jProc is invoked. The level parameter gives the nesting level of the
113 command (1 for top-level commands passed to Tcl_Eval by the applica‐
114 tion, 2 for the next-level commands passed to Tcl_Eval as part of pars‐
115 ing or interpreting level-1 commands, and so on). The command parameter
116 points to a string containing the text of the command, before any argu‐
117 ment substitution. The commandToken parameter is a Tcl command token
118 that identifies the command to be invoked. The token may be passed to
119 Tcl_GetCommandName, Tcl_GetCommandInfoFromToken, or Tcl_SetCommandIn‐
120 foFromToken to manipulate the definition of the command. The objc and
121 objv parameters designate the final parameter count and parameter vec‐
122 tor that will be passed to the command, and have had all substitutions
123 performed.
124 The objProc callback is expected to return a standard Tcl status return
126 code. If this code is TCL_OK (the normal case), then the Tcl inter‐
127 preter will invoke the command. Any other return code is treated as if
128 the command returned that status, and the command is not invoked.
129 The objProc callback must not modify objv in any way. It is, however,
131 permissible to change the command by calling Tcl_SetCommandTokenInfo
132 prior to returning. Any such change takes effect immediately, and the
133 command is invoked with the new information.
134 Tracing will only occur for commands at nesting level less than or
136 equal to the level parameter (i.e. the level parameter to objProc will
137 always be less than or equal to the level parameter to Tcl_Create‐
138 Trace).
139 Tracing has a significant effect on runtime performance because it
141 causes the bytecode compiler to refrain from generating in-line code
142 for Tcl commands such as if and while in order that they may be traced.
143 If traces for the built-in commands are not required, the flags parame‐
144 ter may be set to the constant value TCL_ALLOW_INLINE_COMPILATION. In
145 this case, traces on built-in commands may or may not result in trace
146 callbacks, depending on the state of the interpreter, but run-time per‐
147 formance will be improved significantly. (This functionality is desir‐
148 able, for example, when using Tcl_CreateObjTrace to implement an execu‐
149 tion time profiler.)
150 Calls to objProc will be made by the Tcl parser immediately before it
152 calls the command procedure for the command (cmdProc). This occurs af‐
153 ter argument parsing and substitution, so tracing for substituted com‐
154 mands occurs before tracing of the commands containing the substitu‐
155 tions. If there is a syntax error in a command, or if there is no com‐
156 mand procedure associated with a command name, then no tracing will oc‐
157 cur for that command. If a string passed to Tcl_Eval contains multiple
158 commands (bracketed, or on different lines) then multiple calls to ob‐
159 jProc will occur, one for each command.
160 Tcl_DeleteTrace removes a trace, so that no future calls will be made
162 to the procedure associated with the trace. After Tcl_DeleteTrace re‐
163 turns, the caller should never again use the trace token.
164 When Tcl_DeleteTrace is called, the interpreter invokes the deleteProc
166 that was passed as a parameter to Tcl_CreateObjTrace. The deleteProc
167 must match the type, Tcl_CmdObjTraceDeleteProc:
168 typedef void Tcl_CmdObjTraceDeleteProc(
170 ClientData clientData);
171 The clientData parameter will be the same as the clientData parameter
173 that was originally passed to Tcl_CreateObjTrace.
174 Tcl_CreateTrace is an alternative interface for command tracing, not
176 recommended for new applications. It is provided for backward compati‐
177 bility with code that was developed for older versions of the Tcl in‐
178 terpreter. It is similar to Tcl_CreateObjTrace, except that its proc
179 parameter should have arguments and result that match the type Tcl_Cmd‐
180 TraceProc:
181 typedef void Tcl_CmdTraceProc(
183 ClientData clientData,
184 Tcl_Interp *interp,
185 int level,
186 char *command,
187 Tcl_CmdProc *cmdProc,
188 ClientData cmdClientData,
189 int argc,
190 const char *argv[]);
191 The parameters to the proc callback are similar to those of the objProc
193 callback above. The commandToken is replaced with cmdProc, a pointer to
194 the (string-based) command procedure that will be invoked; and cmd‐
195 ClientData, the client data that will be passed to the procedure. The
196 objc parameter is replaced with an argv parameter, that gives the argu‐
197 ments to the command as character strings. Proc must not modify the
198 command or argv strings.
199 If a trace created with Tcl_CreateTrace is in effect, inline compila‐
201 tion of Tcl commands such as if and while is always disabled. There is
202 no notification when a trace created with Tcl_CreateTrace is deleted.
203 There is no way to be notified when the trace created by Tcl_Create‐
204 Trace is deleted. There is no way for the proc associated with a call
205 to Tcl_CreateTrace to abort execution of command.
206
208 command, create, delete, interpreter, trace
209Tcl Tcl_CreateTrace(3)