util/X86LINUX64/man/man3/Tcl_DeleteTrace.3

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