util/X86LINUX64/man/man3/Tcl_TraceCommand.3

   1 '\"
   2 '\" Copyright (c) 2002 Donal K. Fellows
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .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
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 .SH NAME
 277 Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
 278 .SH SYNOPSIS
 279 .nf
 280 \fB#include <tcl.h>\fR
 281 .sp
 282 ClientData
 283 \fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
 284 .sp
 285 int
 286 \fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
 287 .sp
 288 void
 289 \fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
 290 .SH ARGUMENTS
 291 .AS Tcl_CommandTraceProc prevClientData
 292 .AP Tcl_Interp *interp in
 293 Interpreter containing the command.
 294 .AP "const char" *cmdName in
 295 Name of command.
 296 .AP int flags in
 297 OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
 298 \fBTCL_TRACE_DELETE\fR.
 299 .AP Tcl_CommandTraceProc *proc in
 300 Procedure to call when specified operations occur to \fIcmdName\fR.
 301 .AP ClientData clientData in
 302 Arbitrary argument to pass to \fIproc\fR.
 303 .AP ClientData prevClientData in
 304 If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
 305 so this call will return information about next trace.  If NULL, this
 306 call will return information about first trace.
 307 .BE
 308 .SH DESCRIPTION
 309 .PP
 310 \fBTcl_TraceCommand\fR allows a C procedure to monitor operations
 311 performed on a Tcl command, so that the C procedure is invoked
 312 whenever the command is renamed or deleted.  If the trace is created
 313 successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error
 314 occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
 315 \fBTCL_ERROR\fR is returned and an error message is left in the
 316 interpreter's result.
 317 .PP
 318 The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the
 319 trace procedure is to be invoked.  It consists of an OR'ed combination
 320 of any of the following values:
 321 .TP
 322 \fBTCL_TRACE_RENAME\fR
 323 Invoke \fIproc\fR whenever the command is renamed.
 324 .TP
 325 \fBTCL_TRACE_DELETE\fR
 326 Invoke \fIproc\fR when the command is deleted.
 327 .PP
 328 Whenever one of the specified operations occurs to the command,
 329 \fIproc\fR will be invoked.  It should have arguments and result that
 330 match the type \fBTcl_CommandTraceProc\fR:
 331 .PP
 332 .CS
 333 typedef void \fBTcl_CommandTraceProc\fR(
 334         ClientData \fIclientData\fR,
 335         Tcl_Interp *\fIinterp\fR,
 336         const char *\fIoldName\fR,
 337         const char *\fInewName\fR,
 338         int \fIflags\fR);
 339 .CE
 340 .PP
 341 The \fIclientData\fR and \fIinterp\fR parameters will have the same
 342 values as those passed to \fBTcl_TraceCommand\fR when the trace was
 343 created.  \fIClientData\fR typically points to an application-specific
 344 data structure that describes what to do when \fIproc\fR is invoked.
 345 \fIOldName\fR gives the name of the command being renamed, and
 346 \fInewName\fR gives the name that the command is being renamed to (or
 347 an empty string or NULL when the command is being deleted.)
 348 \fIFlags\fR is an OR'ed combination of bits potentially providing
 349 several pieces of information.  One of the bits \fBTCL_TRACE_RENAME\fR and
 350 \fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
 351 operation is being performed on the command.  The bit
 352 \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about
 353 to be destroyed; this information may be useful to \fIproc\fR so that
 354 it can clean up its own internal data structures (see the section
 355 \fBTCL_TRACE_DESTROYED\fR below for more details).  Because the
 356 deletion of commands can take place as part of the deletion of the interp
 357 that contains them, \fIproc\fR must be careful about checking what
 358 the passed in \fIinterp\fR value can be called upon to do.
 359 The routine \fBTcl_InterpDeleted\fR is an important tool for this.
 360 When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able
 361 to invoke any scripts in \fIinterp\fR.  The function of \fIproc\fR
 362 in that circumstance is limited to the cleanup of its own data structures.
 363 .PP
 364 \fBTcl_UntraceCommand\fR may be used to remove a trace.  If the
 365 command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has
 366 a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then
 367 the corresponding trace is removed.  If no such trace exists, then the
 368 call to \fBTcl_UntraceCommand\fR has no effect.  The same bits are
 369 valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR.
 370 .PP
 371 \fBTcl_CommandTraceInfo\fR may be used to retrieve information about
 372 traces set on a given command.
 373 The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR
 374 associated with a particular trace.
 375 The trace must be on the command specified by the \fIinterp\fR,
 376 \fIcmdName\fR, and \fIflags\fR arguments (note that currently the
 377 flags are ignored; \fIflags\fR should be set to 0 for future
 378 compatibility) and its trace procedure must the same as the \fIproc\fR
 379 argument.
 380 If the \fIprevClientData\fR argument is NULL then the return
 381 value corresponds to the first (most recently created) matching
 382 trace, or NULL if there are no matching traces.
 383 If the \fIprevClientData\fR argument is not NULL, then it should
 384 be the return value from a previous call to \fBTcl_CommandTraceInfo\fR.
 385 In this case, the new return value will correspond to the next
 386 matching trace after the one whose \fIclientData\fR matches
 387 \fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR
 388 or if there are no more matching traces after it.
 389 This mechanism makes it possible to step through all of the
 390 traces for a given command that have the same \fIproc\fR.
 391 .SH "CALLING COMMANDS DURING TRACES"
 392 .PP
 393 During rename traces, the command being renamed is visible with both
 394 names simultaneously, and the command still exists during delete
 395 traces, unless the interp that contains it is being deleted.
 396 However, there is no
 397 mechanism for signaling that an error occurred in a trace procedure,
 398 so great care should be taken that errors do not get silently lost.
 399 .SH "MULTIPLE TRACES"
 400 .PP
 401 It is possible for multiple traces to exist on the same command.
 402 When this happens, all of the trace procedures will be invoked on each
 403 access, in order from most-recently-created to least-recently-created.
 404 Attempts to delete the command during a delete trace will fail
 405 silently, since the command is already scheduled for deletion anyway.
 406 If the command being renamed is renamed by one of its rename traces,
 407 that renaming takes precedence over the one that triggered the trace
 408 and the collection of traces will not be reexecuted; if several traces
 409 rename the command, the last renaming takes precedence.
 410 .SH "TCL_TRACE_DESTROYED FLAG"
 411 .PP
 412 In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
 413 is set in \fIflags\fR.
 414 .\" Perhaps need some more comments here? - DKF
 415 .SH KEYWORDS
 416 clientData, trace, command