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