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
25 to be traced or
26 untraced.
27 int level (in) Only commands at
29 or below this
30 nesting level
31 will be traced
32 unless 0 is
33 specified. 1
34 means top-level
35 commands only, 2
36 means top-level
37 commands or
38 those that are
39 invoked as imme‐
40 diate conse‐
41 quences of exe‐
42 cuting top-level
43 commands (proce‐
44 dure bodies,
45 bracketed com‐
46 mands, etc.) and
47 so on. A value
48 of 0 means that
49 commands at any
50 level are
51 traced.
52 int flags (in) Flags governing
54 the trace execu‐
55 tion. See below
56 for details.
57 Tcl_CmdObjTraceProc *objProc (in) Procedure to
59 call for each
60 command that's
61 executed. See
62 below for
63 details of the
64 calling
65 sequence.
66 Tcl_CmdTraceProc *proc (in) Procedure to
68 call for each
69 command that's
70 executed. See
71 below for
72 details on the
73 calling
74 sequence.
75 ClientData clientData (in) Arbitrary one-
77 word value to
78 pass to objProc
79 or proc.
80 Tcl_CmdObjTraceDeleteProc *deleteProc Procedure to
82 call when the
83 trace is
84 deleted. See
85 below for
86 details of the
87 calling
88 sequence. A
89 NULL pointer is
90 permissible and
91 results in no
92 callback when
93 the trace is
94 deleted.
95 Tcl_Trace trace (in) Token for trace
97 to be removed
98 (return value
99 from previous
100 call to Tcl_Cre‐
101 ateTrace).
102_________________________________________________________________
103
105 Tcl_CreateObjTrace arranges for command tracing. After it is called,
106 objProc will be invoked before the Tcl interpreter calls any command
107 procedure when evaluating commands in interp. The return value from
108 Tcl_CreateObjTrace is a token for the trace, which may be passed to
109 Tcl_DeleteTrace to remove the trace. There may be many traces in
110 effect simultaneously for the same interpreter.
111 objProc should have arguments and result that match the type,
113 Tcl_CmdObjTraceProc:
114 typedef int Tcl_CmdObjTraceProc(
115 ClientData clientData,
116 Tcl_Interp* interp,
117 int level,
118 CONST char* command,
119 Tcl_Command commandToken,
120 int objc,
121 Tcl_Obj *CONST objv[] );
122 The clientData and interp parameters are copies of the corresponding
123 arguments given to Tcl_CreateTrace. ClientData typically points to an
124 application-specific data structure that describes what to do when
125 objProc is invoked. The level parameter gives the nesting level of the
126 command (1 for top-level commands passed to Tcl_Eval by the applica‐
127 tion, 2 for the next-level commands passed to Tcl_Eval as part of pars‐
128 ing or interpreting level-1 commands, and so on). The command parameter
129 points to a string containing the text of the command, before any argu‐
130 ment substitution. The commandToken parameter is a Tcl command token
131 that identifies the command to be invoked. The token may be passed to
132 Tcl_GetCommandName, Tcl_GetCommandTokenInfo, or Tcl_SetCommandTokenInfo
133 to manipulate the definition of the command. The objc and objv parame‐
134 ters designate the final parameter count and parameter vector that will
135 be passed to the command, and have had all substitutions performed.
136 The objProc callback is expected to return a standard Tcl status return
138 code. If this code is TCL_OK (the normal case), then the Tcl inter‐
139 preter will invoke the command. Any other return code is treated as if
140 the command returned that status, and the command is not invoked.
141 The objProc callback must not modify objv in any way. It is, however,
143 permissible to change the command by calling Tcl_SetCommandTokenInfo
144 prior to returning. Any such change takes effect immediately, and the
145 command is invoked with the new information.
146 Tracing will only occur for commands at nesting level less than or
148 equal to the level parameter (i.e. the level parameter to objProc will
149 always be less than or equal to the level parameter to Tcl_Create‐
150 Trace).
151 Tracing has a significant effect on runtime performance because it
153 causes the bytecode compiler to refrain from generating in-line code
154 for Tcl commands such as if and while in order that they may be traced.
155 If traces for the built-in commands are not required, the flags parame‐
156 ter may be set to the constant value TCL_ALLOW_INLINE_COMPILATION. In
157 this case, traces on built-in commands may or may not result in trace
158 callbacks, depending on the state of the interpreter, but run-time per‐
159 formance will be improved significantly. (This functionality is desir‐
160 able, for example, when using Tcl_CreateObjTrace to implement an execu‐
161 tion time profiler.)
162 Calls to objProc will be made by the Tcl parser immediately before it
164 calls the command procedure for the command (cmdProc). This occurs
165 after argument parsing and substitution, so tracing for substituted
166 commands occurs before tracing of the commands containing the substitu‐
167 tions. If there is a syntax error in a command, or if there is no com‐
168 mand procedure associated with a command name, then no tracing will
169 occur for that command. If a string passed to Tcl_Eval contains multi‐
170 ple commands (bracketed, or on different lines) then multiple calls to
171 objProc will occur, one for each command.
172 Tcl_DeleteTrace removes a trace, so that no future calls will be made
174 to the procedure associated with the trace. After Tcl_DeleteTrace
175 returns, the caller should never again use the trace token.
176 When Tcl_DeleteTrace is called, the interpreter invokes the deleteProc
178 that was passed as a parameter to Tcl_CreateObjTrace. The deleteProc
179 must match the type, Tcl_CmdObjTraceDeleteProc:
180 typedef void Tcl_CmdObjTraceDeleteProc(
181 ClientData clientData
182 );
183 The clientData parameter will be the same as the clientData parameter
184 that was originally passed to Tcl_CreateObjTrace.
185 Tcl_CreateTrace is an alternative interface for command tracing, not
187 recommended for new applications. It is provided for backward compati‐
188 bility with code that was developed for older versions of the Tcl
189 interpreter. It is similar to Tcl_CreateObjTrace, except that its proc
190 parameter should have arguments and result that match the type Tcl_Cmd‐
191 TraceProc:
192 typedef void Tcl_CmdTraceProc(
193 ClientData clientData,
194 Tcl_Interp *interp,
195 int level,
196 char *command,
197 Tcl_CmdProc *cmdProc,
198 ClientData cmdClientData,
199 int argc,
200 CONST char *argv[]);
201 The parameters to the proc callback are similar to those of the objProc
202 callback above. The commandToken is replaced with cmdProc, a pointer to
203 the (string-based) command procedure that will be invoked; and cmd‐
204 ClientData, the client data that will be passed to the procedure. The
205 objc parameter is replaced with an argv parameter, that gives the argu‐
206 ments to the command as character strings. Proc must not modify the
207 command or argv strings.
208 If a trace created with Tcl_CreateTrace is in effect, inline compila‐
210 tion of Tcl commands such as if and while is always disabled. There is
211 no notification when a trace created with Tcl_CreateTrace is deleted.
212 There is no way to be notified when the trace created by Tcl_Create‐
213 Trace is deleted. There is no way for the proc associated with a call
214 to Tcl_CreateTrace to abort execution of command.
215
217 command, create, delete, interpreter, trace
218Tcl Tcl_CreateTrace(3)