Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1989-1993 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
4 | '\" Copyright (c) 2002 by Kevin B. Kenny. All rights reserved. | |
5 | '\" | |
6 | '\" See the file "license.terms" for information on usage and redistribution | |
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
8 | '\" | |
9 | '\" RCS: @(#) $Id: CrtTrace.3,v 1.6.2.1 2003/07/18 15:20:51 dgp Exp $ | |
10 | '\" | |
11 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
12 | '\" manual entries. | |
13 | '\" | |
14 | '\" .AP type name in/out ?indent? | |
15 | '\" Start paragraph describing an argument to a library procedure. | |
16 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
17 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
18 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
19 | '\" needed; use .AS below instead) | |
20 | '\" | |
21 | '\" .AS ?type? ?name? | |
22 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
23 | '\" name are examples of largest possible arguments that will be passed | |
24 | '\" to .AP later. If args are omitted, default tab stops are used. | |
25 | '\" | |
26 | '\" .BS | |
27 | '\" Start box enclosure. From here until next .BE, everything will be | |
28 | '\" enclosed in one large box. | |
29 | '\" | |
30 | '\" .BE | |
31 | '\" End of box enclosure. | |
32 | '\" | |
33 | '\" .CS | |
34 | '\" Begin code excerpt. | |
35 | '\" | |
36 | '\" .CE | |
37 | '\" End code excerpt. | |
38 | '\" | |
39 | '\" .VS ?version? ?br? | |
40 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
41 | '\" of man pages. The first argument is ignored and used for recording | |
42 | '\" the version when the .VS was added, so that the sidebars can be | |
43 | '\" found and removed when they reach a certain age. If another argument | |
44 | '\" is present, then a line break is forced before starting the sidebar. | |
45 | '\" | |
46 | '\" .VE | |
47 | '\" End of vertical sidebar. | |
48 | '\" | |
49 | '\" .DS | |
50 | '\" Begin an indented unfilled display. | |
51 | '\" | |
52 | '\" .DE | |
53 | '\" End of indented unfilled display. | |
54 | '\" | |
55 | '\" .SO | |
56 | '\" Start of list of standard options for a Tk widget. The | |
57 | '\" options follow on successive lines, in four columns separated | |
58 | '\" by tabs. | |
59 | '\" | |
60 | '\" .SE | |
61 | '\" End of list of standard options for a Tk widget. | |
62 | '\" | |
63 | '\" .OP cmdName dbName dbClass | |
64 | '\" Start of description of a specific option. cmdName gives the | |
65 | '\" option's name as specified in the class command, dbName gives | |
66 | '\" the option's name in the option database, and dbClass gives | |
67 | '\" the option's class in the option database. | |
68 | '\" | |
69 | '\" .UL arg1 arg2 | |
70 | '\" Print arg1 underlined, then print arg2 normally. | |
71 | '\" | |
72 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
73 | '\" | |
74 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
75 | .if t .wh -1.3i ^B | |
76 | .nr ^l \n(.l | |
77 | .ad b | |
78 | '\" # Start an argument description | |
79 | .de AP | |
80 | .ie !"\\$4"" .TP \\$4 | |
81 | .el \{\ | |
82 | . ie !"\\$2"" .TP \\n()Cu | |
83 | . el .TP 15 | |
84 | .\} | |
85 | .ta \\n()Au \\n()Bu | |
86 | .ie !"\\$3"" \{\ | |
87 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
88 | .\".b | |
89 | .\} | |
90 | .el \{\ | |
91 | .br | |
92 | .ie !"\\$2"" \{\ | |
93 | \&\\$1 \\fI\\$2\\fP | |
94 | .\} | |
95 | .el \{\ | |
96 | \&\\fI\\$1\\fP | |
97 | .\} | |
98 | .\} | |
99 | .. | |
100 | '\" # define tabbing values for .AP | |
101 | .de AS | |
102 | .nr )A 10n | |
103 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
104 | .nr )B \\n()Au+15n | |
105 | .\" | |
106 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
107 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
108 | .. | |
109 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
110 | '\" # BS - start boxed text | |
111 | '\" # ^y = starting y location | |
112 | '\" # ^b = 1 | |
113 | .de BS | |
114 | .br | |
115 | .mk ^y | |
116 | .nr ^b 1u | |
117 | .if n .nf | |
118 | .if n .ti 0 | |
119 | .if n \l'\\n(.lu\(ul' | |
120 | .if n .fi | |
121 | .. | |
122 | '\" # BE - end boxed text (draw box now) | |
123 | .de BE | |
124 | .nf | |
125 | .ti 0 | |
126 | .mk ^t | |
127 | .ie n \l'\\n(^lu\(ul' | |
128 | .el \{\ | |
129 | .\" Draw four-sided box normally, but don't draw top of | |
130 | .\" box if the box started on an earlier page. | |
131 | .ie !\\n(^b-1 \{\ | |
132 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
133 | .\} | |
134 | .el \}\ | |
135 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
136 | .\} | |
137 | .\} | |
138 | .fi | |
139 | .br | |
140 | .nr ^b 0 | |
141 | .. | |
142 | '\" # VS - start vertical sidebar | |
143 | '\" # ^Y = starting y location | |
144 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
145 | .de VS | |
146 | .if !"\\$2"" .br | |
147 | .mk ^Y | |
148 | .ie n 'mc \s12\(br\s0 | |
149 | .el .nr ^v 1u | |
150 | .. | |
151 | '\" # VE - end of vertical sidebar | |
152 | .de VE | |
153 | .ie n 'mc | |
154 | .el \{\ | |
155 | .ev 2 | |
156 | .nf | |
157 | .ti 0 | |
158 | .mk ^t | |
159 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
160 | .sp -1 | |
161 | .fi | |
162 | .ev | |
163 | .\} | |
164 | .nr ^v 0 | |
165 | .. | |
166 | '\" # Special macro to handle page bottom: finish off current | |
167 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
168 | '\" # page bottom macro. | |
169 | .de ^B | |
170 | .ev 2 | |
171 | 'ti 0 | |
172 | 'nf | |
173 | .mk ^t | |
174 | .if \\n(^b \{\ | |
175 | .\" Draw three-sided box if this is the box's first page, | |
176 | .\" draw two sides but no top otherwise. | |
177 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
178 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
179 | .\} | |
180 | .if \\n(^v \{\ | |
181 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
182 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
183 | .\} | |
184 | .bp | |
185 | 'fi | |
186 | .ev | |
187 | .if \\n(^b \{\ | |
188 | .mk ^y | |
189 | .nr ^b 2 | |
190 | .\} | |
191 | .if \\n(^v \{\ | |
192 | .mk ^Y | |
193 | .\} | |
194 | .. | |
195 | '\" # DS - begin display | |
196 | .de DS | |
197 | .RS | |
198 | .nf | |
199 | .sp | |
200 | .. | |
201 | '\" # DE - end display | |
202 | .de DE | |
203 | .fi | |
204 | .RE | |
205 | .sp | |
206 | .. | |
207 | '\" # SO - start of list of standard options | |
208 | .de SO | |
209 | .SH "STANDARD OPTIONS" | |
210 | .LP | |
211 | .nf | |
212 | .ta 5.5c 11c | |
213 | .ft B | |
214 | .. | |
215 | '\" # SE - end of list of standard options | |
216 | .de SE | |
217 | .fi | |
218 | .ft R | |
219 | .LP | |
220 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
221 | .. | |
222 | '\" # OP - start of full description for a single option | |
223 | .de OP | |
224 | .LP | |
225 | .nf | |
226 | .ta 4c | |
227 | Command-Line Name: \\fB\\$1\\fR | |
228 | Database Name: \\fB\\$2\\fR | |
229 | Database Class: \\fB\\$3\\fR | |
230 | .fi | |
231 | .IP | |
232 | .. | |
233 | '\" # CS - begin code excerpt | |
234 | .de CS | |
235 | .RS | |
236 | .nf | |
237 | .ta .25i .5i .75i 1i | |
238 | .. | |
239 | '\" # CE - end code excerpt | |
240 | .de CE | |
241 | .fi | |
242 | .RE | |
243 | .. | |
244 | .de UL | |
245 | \\$1\l'|0\(ul'\\$2 | |
246 | .. | |
247 | .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" | |
248 | .BS | |
249 | .SH NAME | |
250 | Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced | |
251 | .SH SYNOPSIS | |
252 | .nf | |
253 | \fB#include <tcl.h>\fR | |
254 | .sp | |
255 | Tcl_Trace | |
256 | \fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR) | |
257 | .sp | |
258 | Tcl_Trace | |
259 | \fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR) | |
260 | .sp | |
261 | \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) | |
262 | .SH ARGUMENTS | |
263 | .AS Tcl_CmdObjTraceDeleteProc (clientData)() | |
264 | .AP Tcl_Interp *interp in | |
265 | Interpreter containing command to be traced or untraced. | |
266 | .AP int level in | |
267 | Only commands at or below this nesting level will be traced unless | |
268 | 0 is specified. 1 means | |
269 | top-level commands only, 2 means top-level commands or those that are | |
270 | invoked as immediate consequences of executing top-level commands | |
271 | (procedure bodies, bracketed commands, etc.) and so on. | |
272 | A value of 0 means that commands at any level are traced. | |
273 | .AP int flags in | |
274 | Flags governing the trace execution. See below for details. | |
275 | .AP Tcl_CmdObjTraceProc *objProc in | |
276 | Procedure to call for each command that's executed. See below for | |
277 | details of the calling sequence. | |
278 | .AP Tcl_CmdTraceProc *proc in | |
279 | Procedure to call for each command that's executed. See below for | |
280 | details on the calling sequence. | |
281 | .AP ClientData clientData in | |
282 | Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR. | |
283 | .AP Tcl_CmdObjTraceDeleteProc *deleteProc | |
284 | Procedure to call when the trace is deleted. See below for details of | |
285 | the calling sequence. A NULL pointer is permissible and results in no | |
286 | callback when the trace is deleted. | |
287 | .AP Tcl_Trace trace in | |
288 | Token for trace to be removed (return value from previous call | |
289 | to \fBTcl_CreateTrace\fR). | |
290 | .BE | |
291 | .SH DESCRIPTION | |
292 | .PP | |
293 | \fBTcl_CreateObjTrace\fR arranges for command tracing. After it is | |
294 | called, \fIobjProc\fR will be invoked before the Tcl interpreter calls | |
295 | any command procedure when evaluating commands in \fIinterp\fR. | |
296 | The return value from \fBTcl_CreateObjTrace\fR is a token for the trace, | |
297 | which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. | |
298 | There may be many traces in effect simultaneously for the same | |
299 | interpreter. | |
300 | .PP | |
301 | \fIobjProc\fR should have arguments and result that match the type, | |
302 | \fBTcl_CmdObjTraceProc\fR: | |
303 | .CS | |
304 | typedef int \fBTcl_CmdObjTraceProc\fR( | |
305 | \fBClientData\fR \fIclientData\fR, | |
306 | \fBTcl_Interp\fR* \fIinterp\fR, | |
307 | int \fIlevel\fR, | |
308 | CONST char* \fIcommand\fR, | |
309 | \fBTcl_Command\fR \fIcommandToken\fR, | |
310 | int \fIobjc\fR, | |
311 | \fBTcl_Obj\fR *CONST \fIobjv\fR[] ); | |
312 | .CE | |
313 | The \fIclientData\fR and \fIinterp\fR parameters are copies of the | |
314 | corresponding arguments given to \fBTcl_CreateTrace\fR. | |
315 | \fIClientData\fR typically points to an application-specific data | |
316 | structure that describes what to do when \fIobjProc\fR is invoked. The | |
317 | \fIlevel\fR parameter gives the nesting level of the command (1 for | |
318 | top-level commands passed to \fBTcl_Eval\fR by the application, 2 for | |
319 | the next-level commands passed to \fBTcl_Eval\fR as part of parsing or | |
320 | interpreting level-1 commands, and so on). The \fIcommand\fR parameter | |
321 | points to a string containing the text of the command, before any | |
322 | argument substitution. The \fIcommandToken\fR parameter is a Tcl | |
323 | command token that identifies the command to be invoked. The token | |
324 | may be passed to \fBTcl_GetCommandName\fR, | |
325 | \fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to | |
326 | manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR | |
327 | parameters designate the final parameter count and parameter vector | |
328 | that will be passed to the command, and have had all substitutions | |
329 | performed. | |
330 | .PP | |
331 | The \fIobjProc\fR callback is expected to return a standard Tcl status | |
332 | return code. If this code is \fBTCL_OK\fR (the normal case), then | |
333 | the Tcl interpreter will invoke the command. Any other return code | |
334 | is treated as if the command returned that status, and the command is | |
335 | \fInot\fR invoked. | |
336 | .PP | |
337 | The \fIobjProc\fR callback must not modify \fIobjv\fR in any way. It | |
338 | is, however, permissible to change the command by calling | |
339 | \fBTcl_SetCommandTokenInfo\fR prior to returning. Any such change | |
340 | takes effect immediately, and the command is invoked with the new | |
341 | information. | |
342 | .PP | |
343 | Tracing will only occur for commands at nesting level less than | |
344 | or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR | |
345 | parameter to \fIobjProc\fR will always be less than or equal to the | |
346 | \fIlevel\fR parameter to \fBTcl_CreateTrace\fR). | |
347 | .PP | |
348 | Tracing has a significant effect on runtime performance because it | |
349 | causes the bytecode compiler to refrain from generating in-line code | |
350 | for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they | |
351 | may be traced. If traces for the built-in commands are not required, | |
352 | the \fIflags\fR parameter may be set to the constant value | |
353 | \fBTCL_ALLOW_INLINE_COMPILATION\fR. In this case, traces on built-in | |
354 | commands may or may not result in trace callbacks, depending on the | |
355 | state of the interpreter, but run-time performance will be improved | |
356 | significantly. (This functionality is desirable, for example, when | |
357 | using \fBTcl_CreateObjTrace\fR to implement an execution time | |
358 | profiler.) | |
359 | .PP | |
360 | Calls to \fIobjProc\fR will be made by the Tcl parser immediately before | |
361 | it calls the command procedure for the command (\fIcmdProc\fR). This | |
362 | occurs after argument parsing and substitution, so tracing for | |
363 | substituted commands occurs before tracing of the commands | |
364 | containing the substitutions. If there is a syntax error in a | |
365 | command, or if there is no command procedure associated with a | |
366 | command name, then no tracing will occur for that command. If a | |
367 | string passed to Tcl_Eval contains multiple commands (bracketed, or | |
368 | on different lines) then multiple calls to \fIobjProc\fR will occur, | |
369 | one for each command. | |
370 | .PP | |
371 | \fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be | |
372 | made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR | |
373 | returns, the caller should never again use the \fItrace\fR token. | |
374 | .PP | |
375 | When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the | |
376 | \fIdeleteProc\fR that was passed as a parameter to | |
377 | \fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type, | |
378 | \fBTcl_CmdObjTraceDeleteProc\fR: | |
379 | .CS | |
380 | typedef void \fBTcl_CmdObjTraceDeleteProc\fR( | |
381 | \fBClientData\fR \fIclientData\fR | |
382 | ); | |
383 | .CE | |
384 | The \fIclientData\fR parameter will be the same as the | |
385 | \fIclientData\fR parameter that was originally passed to | |
386 | \fBTcl_CreateObjTrace\fR. | |
387 | .PP | |
388 | \fBTcl_CreateTrace\fR is an alternative interface for command tracing, | |
389 | \fInot recommended for new applications\fR. It is provided for backward | |
390 | compatibility with code that was developed for older versions of the | |
391 | Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except | |
392 | that its \fIproc\fR parameter should have arguments and result that | |
393 | match the type \fBTcl_CmdTraceProc\fR: | |
394 | .CS | |
395 | typedef void Tcl_CmdTraceProc( | |
396 | ClientData \fIclientData\fR, | |
397 | Tcl_Interp *\fIinterp\fR, | |
398 | int \fIlevel\fR, | |
399 | char *\fIcommand\fR, | |
400 | Tcl_CmdProc *\fIcmdProc\fR, | |
401 | ClientData \fIcmdClientData\fR, | |
402 | int \fIargc\fR, | |
403 | CONST char *\fIargv\fR[]); | |
404 | .CE | |
405 | The parameters to the \fIproc\fR callback are similar to those of the | |
406 | \fIobjProc\fR callback above. The \fIcommandToken\fR is | |
407 | replaced with \fIcmdProc\fR, a pointer to the (string-based) command | |
408 | procedure that will be invoked; and \fIcmdClientData\fR, the client | |
409 | data that will be passed to the procedure. The \fIobjc\fR parameter | |
410 | is replaced with an \fIargv\fR parameter, that gives the arguments to | |
411 | the command as character strings. | |
412 | \fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings. | |
413 | .PP | |
414 | If a trace created with \fBTcl_CreateTrace\fR is in effect, inline | |
415 | compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always | |
416 | disabled. There is no notification when a trace created with | |
417 | \fBTcl_CreateTrace\fR is deleted. | |
418 | There is no way to be notified when the trace created by | |
419 | \fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR | |
420 | associated with a call to \fBTcl_CreateTrace\fR to abort execution of | |
421 | \fIcommand\fR. | |
422 | .SH KEYWORDS | |
423 | command, create, delete, interpreter, trace |