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
26 untraced.
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
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 int flags (in) Flags governing the
49 trace execution.
50 See below for
51 details.
52 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 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 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
78 results 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
95 effect simultaneously for the same interpreter.
96 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 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 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 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 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 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 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 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 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 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
202 command, create, delete, interpreter, trace
203Tcl Tcl_CreateTrace(3)