2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 '\" RCS: @(#) $Id: CrtTrace.3,v 1.2 1998/09/14 18:39:47 stanton Exp $
10 '\" The definitions below are for supplemental macros used in Tcl/Tk
13 '\" .AP type name in/out ?indent?
14 '\" Start paragraph describing an argument to a library procedure.
15 '\" type is type of argument (int, etc.), in/out is either "in", "out",
16 '\" or "in/out" to describe whether procedure reads or modifies arg,
17 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 '\" needed; use .AS below instead)
21 '\" Give maximum sizes of arguments for setting tab stops. Type and
22 '\" name are examples of largest possible arguments that will be passed
23 '\" to .AP later. If args are omitted, default tab stops are used.
26 '\" Start box enclosure. From here until next .BE, everything will be
27 '\" enclosed in one large box.
30 '\" End of box enclosure.
33 '\" Begin code excerpt.
38 '\" .VS ?version? ?br?
39 '\" Begin vertical sidebar, for use in marking newly-changed parts
40 '\" of man pages. The first argument is ignored and used for recording
41 '\" the version when the .VS was added, so that the sidebars can be
42 '\" found and removed when they reach a certain age. If another argument
43 '\" is present, then a line break is forced before starting the sidebar.
46 '\" End of vertical sidebar.
49 '\" Begin an indented unfilled display.
52 '\" End of indented unfilled display.
55 '\" Start of list of standard options for a Tk widget. The
56 '\" options follow on successive lines, in four columns separated
60 '\" End of list of standard options for a Tk widget.
62 '\" .OP cmdName dbName dbClass
63 '\" Start of description of a specific option. cmdName gives the
64 '\" option's name as specified in the class command, dbName gives
65 '\" the option's name in the option database, and dbClass gives
66 '\" the option's class in the option database.
69 '\" Print arg1 underlined, then print arg2 normally.
71 '\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
77 '\" # Start an argument description
81 . ie !"\\$2"" .TP \\n()Cu
86 \&\\$1 \\fI\\$2\\fP (\\$3)
99 '\" # define tabbing values for .AP
102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
118 .if n \l'\\n(.lu\(ul'
121 '\" # BE - end boxed text (draw box now)
126 .ie n \l'\\n(^lu\(ul'
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box if the box started on an earlier page.
131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
147 .ie n 'mc \s12\(br\s0
150 '\" # VE - end of vertical sidebar
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
165 '\" # Special macro to handle page bottom: finish off current
166 '\" # box/sidebar if in box/sidebar mode, then invoked standard
167 '\" # page bottom macro.
174 .\" Draw three-sided box if this is the box's first page,
175 .\" draw two sides but no top otherwise.
176 .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
177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
180 .nr ^x \\n(^tu+1v-\\n(^Yu
181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
194 '\" # DS - begin display
200 '\" # DE - end display
206 '\" # SO - start of list of standard options
208 .SH "STANDARD OPTIONS"
214 '\" # SE - end of list of standard options
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
238 '\" # CE - end code excerpt
246 .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
249 Tcl_CreateTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
252 \fB#include <tcl.h>\fR
255 \fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
257 \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
259 .AS Tcl_CmdTraceProc (clientData)()
260 .AP Tcl_Interp *interp in
261 Interpreter containing command to be traced or untraced.
263 Only commands at or below this nesting level will be traced. 1 means
264 top-level commands only, 2 means top-level commands or those that are
265 invoked as immediate consequences of executing top-level commands
266 (procedure bodies, bracketed commands, etc.) and so on.
267 .AP Tcl_CmdTraceProc *proc in
268 Procedure to call for each command that's executed. See below for
269 details on the calling sequence.
270 .AP ClientData clientData in
271 Arbitrary one-word value to pass to \fIproc\fR.
272 .AP Tcl_Trace trace in
273 Token for trace to be removed (return value from previous call
274 to \fBTcl_CreateTrace\fR).
279 \fBTcl_CreateTrace\fR arranges for command tracing. From now on, \fIproc\fR
280 will be invoked before Tcl calls command procedures to process
281 commands in \fIinterp\fR. The return value from
282 \fBTcl_CreateTrace\fR is a token for the trace,
283 which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. There may
284 be many traces in effect simultaneously for the same command interpreter.
286 \fIProc\fR should have arguments and result that match the
287 type \fBTcl_CmdTraceProc\fR:
289 typedef void Tcl_CmdTraceProc(
290 ClientData \fIclientData\fR,
291 Tcl_Interp *\fIinterp\fR,
294 Tcl_CmdProc *\fIcmdProc\fR,
295 ClientData \fIcmdClientData\fR,
299 The \fIclientData\fR and \fIinterp\fR parameters are
300 copies of the corresponding arguments given to \fBTcl_CreateTrace\fR.
301 \fIClientData\fR typically points to an application-specific
302 data structure that describes what to do when \fIproc\fR
303 is invoked. \fILevel\fR gives the nesting level of the command
304 (1 for top-level commands passed to \fBTcl_Eval\fR by the application,
305 2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing
306 or interpreting level-1 commands, and so on). \fICommand\fR
307 points to a string containing the text of the
308 command, before any argument substitution.
309 \fICmdProc\fR contains the address of the command procedure that
310 will be called to process the command (i.e. the \fIproc\fR argument
311 of some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
312 contains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
313 value passed to \fBTcl_CreateCommand\fR). \fIArgc\fR and \fIargv\fR give
314 the final argument information that will be passed to \fIcmdProc\fR, after
315 command, variable, and backslash substitution.
316 \fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
318 Tracing will only occur for commands at nesting level less than
319 or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
320 parameter to \fIproc\fR will always be less than or equal to the
321 \fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
323 Calls to \fIproc\fR will be made by the Tcl parser immediately before
324 it calls the command procedure for the command (\fIcmdProc\fR). This
325 occurs after argument parsing and substitution, so tracing for
326 substituted commands occurs before tracing of the commands
327 containing the substitutions. If there is a syntax error in a
328 command, or if there is no command procedure associated with a
329 command name, then no tracing will occur for that command. If a
330 string passed to Tcl_Eval contains multiple commands (bracketed, or
331 on different lines) then multiple calls to \fIproc\fR will occur,
332 one for each command. The \fIcommand\fR string for each of these
333 trace calls will reflect only a single command, not the entire string
336 \fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be
337 made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR
338 returns, the caller should never again use the \fItrace\fR token.
341 command, create, delete, interpreter, trace