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 .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
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)
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.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
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.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
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.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .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
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable
281 \fB#include <tcl.h>\fR
284 \fBTcl_TraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR
287 \fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
289 \fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR
291 \fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
294 \fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR
297 \fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR
299 .AS Tcl_VarTraceProc prevClientData
300 .AP Tcl_Interp *interp in
301 Interpreter containing variable.
302 .AP "const char" *varName in
303 Name of variable. May refer to a scalar variable, to
304 an array variable with no index, or to an array variable
305 with a parenthesized index.
307 OR-ed combination of the values \fBTCL_TRACE_READS\fR,
308 \fBTCL_TRACE_WRITES\fR, \fBTCL_TRACE_UNSETS\fR, \fBTCL_TRACE_ARRAY\fR,
309 \fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR,
310 \fBTCL_TRACE_RESULT_DYNAMIC\fR and \fBTCL_TRACE_RESULT_OBJECT\fR.
311 Not all flags are used by all
312 procedures. See below for more information.
313 .AP Tcl_VarTraceProc *proc in
314 Procedure to invoke whenever one of the traced operations occurs.
315 .AP ClientData clientData in
316 Arbitrary one-word value to pass to \fIproc\fR.
317 .AP "const char" *name1 in
318 Name of scalar or array variable (without array index).
319 .AP "const char" *name2 in
320 For a trace on an element of an array, gives the index of the
321 element. For traces on scalar variables or on whole arrays,
323 .AP ClientData prevClientData in
324 If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
325 \fBTcl_VarTraceInfo2\fR, so this call will return information about
326 next trace. If NULL, this call will return information about first
331 \fBTcl_TraceVar\fR allows a C procedure to monitor and control
332 access to a Tcl variable, so that the C procedure is invoked
333 whenever the variable is read or written or unset.
334 If the trace is created successfully then \fBTcl_TraceVar\fR returns
335 \fBTCL_OK\fR. If an error occurred (e.g. \fIvarName\fR specifies an element
336 of an array, but the actual variable is not an array) then \fBTCL_ERROR\fR
337 is returned and an error message is left in the interpreter's result.
339 The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the
340 trace procedure is to be invoked and provides information
341 for setting up the trace. It consists of an OR-ed combination
342 of any of the following values:
344 \fBTCL_GLOBAL_ONLY\fR
345 Normally, the variable will be looked up at the current level of
346 procedure call; if this bit is set then the variable will be looked
347 up at global level, ignoring any active procedures.
349 \fBTCL_NAMESPACE_ONLY\fR
350 Normally, the variable will be looked up at the current level of
351 procedure call; if this bit is set then the variable will be looked
352 up in the current namespace, ignoring any active procedures.
354 \fBTCL_TRACE_READS\fR
355 Invoke \fIproc\fR whenever an attempt is made to read the variable.
357 \fBTCL_TRACE_WRITES\fR
358 Invoke \fIproc\fR whenever an attempt is made to modify the variable.
360 \fBTCL_TRACE_UNSETS\fR
361 Invoke \fIproc\fR whenever the variable is unset.
362 A variable may be unset either explicitly by an \fBunset\fR command,
363 or implicitly when a procedure returns (its local variables are
364 automatically unset) or when the interpreter is deleted (all
365 variables are automatically unset).
367 \fBTCL_TRACE_ARRAY\fR
368 Invoke \fIproc\fR whenever the array command is invoked.
369 This gives the trace procedure a chance to update the array before
370 array names or array get is called. Note that this is called
371 before an array set, but that will trigger write traces.
373 \fBTCL_TRACE_RESULT_DYNAMIC\fR
374 The result of invoking the \fIproc\fR is a dynamically allocated
375 string that will be released by the Tcl library via a call to
376 \fBckfree\fR. Must not be specified at the same time as
377 \fBTCL_TRACE_RESULT_OBJECT\fR.
379 \fBTCL_TRACE_RESULT_OBJECT\fR
380 The result of invoking the \fIproc\fR is a Tcl_Obj* (cast to a char*)
381 with a reference count of at least one. The ownership of that
382 reference will be transferred to the Tcl core for release (when the
383 core has finished with it) via a call to \fBTcl_DecrRefCount\fR. Must
384 not be specified at the same time as \fBTCL_TRACE_RESULT_DYNAMIC\fR.
386 Whenever one of the specified operations occurs on the variable,
387 \fIproc\fR will be invoked.
388 It should have arguments and result that match the type
389 \fBTcl_VarTraceProc\fR:
392 typedef char *\fBTcl_VarTraceProc\fR(
393 ClientData \fIclientData\fR,
394 Tcl_Interp *\fIinterp\fR,
400 The \fIclientData\fR and \fIinterp\fR parameters will
401 have the same values as those passed to \fBTcl_TraceVar\fR when the
403 \fIClientData\fR typically points to an application-specific
404 data structure that describes what to do when \fIproc\fR
406 \fIName1\fR and \fIname2\fR give the name of the traced variable
407 in the normal two-part form (see the description of \fBTcl_TraceVar2\fR
409 \fIFlags\fR is an OR-ed combination of bits providing several
410 pieces of information.
411 One of the bits \fBTCL_TRACE_READS\fR, \fBTCL_TRACE_WRITES\fR,
412 \fBTCL_TRACE_ARRAY\fR, or \fBTCL_TRACE_UNSETS\fR
413 will be set in \fIflags\fR to indicate which operation is being performed
415 The bit \fBTCL_GLOBAL_ONLY\fR will be set whenever the variable being
416 accessed is a global one not accessible from the current level of
417 procedure call: the trace procedure will need to pass this flag
418 back to variable-related procedures like \fBTcl_GetVar\fR if it
419 attempts to access the variable.
420 The bit \fBTCL_NAMESPACE_ONLY\fR will be set whenever the variable being
421 accessed is a namespace one not accessible from the current level of
422 procedure call: the trace procedure will need to pass this flag
423 back to variable-related procedures like \fBTcl_GetVar\fR if it
424 attempts to access the variable.
425 The bit \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is
426 about to be destroyed; this information may be useful to \fIproc\fR
427 so that it can clean up its own internal data structures (see
428 the section \fBTCL_TRACE_DESTROYED\fR below for more details).
429 Lastly, the bit \fBTCL_INTERP_DESTROYED\fR will be set if the entire
430 interpreter is being destroyed.
431 When this bit is set, \fIproc\fR must be especially careful in
432 the things it does (see the section \fBTCL_INTERP_DESTROYED\fR below).
433 The trace procedure's return value should normally be NULL; see
434 \fBERROR RETURNS\fR below for information on other possibilities.
436 \fBTcl_UntraceVar\fR may be used to remove a trace.
437 If the variable specified by \fIinterp\fR, \fIvarName\fR, and \fIflags\fR
438 has a trace set with \fIflags\fR, \fIproc\fR, and
439 \fIclientData\fR, then the corresponding trace is removed.
440 If no such trace exists, then the call to \fBTcl_UntraceVar\fR
442 The same bits are valid for \fIflags\fR as for calls to \fBTcl_TraceVar\fR.
444 \fBTcl_VarTraceInfo\fR may be used to retrieve information about
445 traces set on a given variable.
446 The return value from \fBTcl_VarTraceInfo\fR is the \fIclientData\fR
447 associated with a particular trace.
448 The trace must be on the variable specified by the \fIinterp\fR,
449 \fIvarName\fR, and \fIflags\fR arguments (only the \fBTCL_GLOBAL_ONLY\fR and
450 \fBTCL_NAMESPACE_ONLY\fR bits from \fIflags\fR is used; other bits are
451 ignored) and its trace procedure must the same as the \fIproc\fR
453 If the \fIprevClientData\fR argument is NULL then the return
454 value corresponds to the first (most recently created) matching
455 trace, or NULL if there are no matching traces.
456 If the \fIprevClientData\fR argument is not NULL, then it should
457 be the return value from a previous call to \fBTcl_VarTraceInfo\fR.
458 In this case, the new return value will correspond to the next
459 matching trace after the one whose \fIclientData\fR matches
460 \fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR
461 or if there are no more matching traces after it.
462 This mechanism makes it possible to step through all of the
463 traces for a given variable that have the same \fIproc\fR.
466 The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and
467 \fBTcl_VarTraceInfo2\fR are identical to \fBTcl_TraceVar\fR,
468 \fBTcl_UntraceVar\fR, and \fBTcl_VarTraceInfo\fR, respectively,
469 except that the name of the variable consists of two parts.
470 \fIName1\fR gives the name of a scalar variable or array,
471 and \fIname2\fR gives the name of an element within an array.
472 When \fIname2\fR is NULL,
473 \fIname1\fR may contain both an array and an element name:
474 if the name contains an open parenthesis and ends with a
475 close parenthesis, then the value between the parentheses is
476 treated as an element name (which can have any string value) and
477 the characters before the first open
478 parenthesis are treated as the name of an array variable.
479 If \fIname2\fR is NULL and \fIname1\fR does not refer
480 to an array element it means that either the variable is
481 a scalar or the trace is to be set on the entire array rather
482 than an individual element (see WHOLE-ARRAY TRACES below for
484 .SH "ACCESSING VARIABLES DURING TRACES"
486 During read, write, and array traces, the
487 trace procedure can read, write, or unset the traced
488 variable using \fBTcl_GetVar2\fR, \fBTcl_SetVar2\fR, and
490 While \fIproc\fR is executing, traces are temporarily disabled
491 for the variable, so that calls to \fBTcl_GetVar2\fR and
492 \fBTcl_SetVar2\fR will not cause \fIproc\fR or other trace procedures
494 Disabling only occurs for the variable whose trace procedure
495 is active; accesses to other variables will still be traced.
496 However, if a variable is unset during a read or write trace then unset
497 traces will be invoked.
499 During unset traces the variable has already been completely
501 It is possible for the trace procedure to read or write the
502 variable, but this will be a new version of the variable.
503 Traces are not disabled during unset traces as they are for
504 read and write traces, but existing traces have been removed
505 from the variable before any trace procedures are invoked.
506 If new traces are set by unset trace procedures, these traces
507 will be invoked on accesses to the variable by the trace
509 .SH "CALLBACK TIMING"
511 When read tracing has been specified for a variable, the trace
512 procedure will be invoked whenever the variable's value is
513 read. This includes \fBset\fR Tcl commands, \fB$\fR-notation
514 in Tcl commands, and invocations of the \fBTcl_GetVar\fR
515 and \fBTcl_GetVar2\fR procedures.
516 \fIProc\fR is invoked just before the variable's value is
518 It may modify the value of the variable to affect what
519 is returned by the traced access.
520 If it unsets the variable then the access will return an error
521 just as if the variable never existed.
523 When write tracing has been specified for a variable, the
524 trace procedure will be invoked whenever the variable's value
525 is modified. This includes \fBset\fR commands,
526 commands that modify variables as side effects (such as
527 \fBcatch\fR and \fBscan\fR), and calls to the \fBTcl_SetVar\fR
528 and \fBTcl_SetVar2\fR procedures).
529 \fIProc\fR will be invoked after the variable's value has been
530 modified, but before the new value of the variable has been
532 It may modify the value of the variable to override the change
533 and to determine the value actually returned by the traced
535 If it deletes the variable then the traced access will return
538 When array tracing has been specified, the trace procedure
539 will be invoked at the beginning of the array command implementation,
540 before any of the operations like get, set, or names have been invoked.
541 The trace procedure can modify the array elements with \fBTcl_SetVar\fR
542 and \fBTcl_SetVar2\fR.
544 When unset tracing has been specified, the trace procedure
545 will be invoked whenever the variable is destroyed.
546 The traces will be called after the variable has been
548 .SH "WHOLE-ARRAY TRACES"
550 If a call to \fBTcl_TraceVar\fR or \fBTcl_TraceVar2\fR specifies
551 the name of an array variable without an index into the array,
552 then the trace will be set on the array as a whole.
553 This means that \fIproc\fR will be invoked whenever any
554 element of the array is accessed in the ways specified by
556 When an array is unset, a whole-array trace will be invoked
557 just once, with \fIname1\fR equal to the name of the array
558 and \fIname2\fR NULL; it will not be invoked once for each
560 .SH "MULTIPLE TRACES"
562 It is possible for multiple traces to exist on the same variable.
563 When this happens, all of the trace procedures will be invoked on each
564 access, in order from most-recently-created to least-recently-created.
565 When there exist whole-array traces for an array as well as
566 traces on individual elements, the whole-array traces are invoked
567 before the individual-element traces.
568 If a read or write trace unsets the variable then all of the unset
569 traces will be invoked but the remainder of the read and write traces
573 Under normal conditions trace procedures should return NULL, indicating
574 successful completion.
575 If \fIproc\fR returns a non-NULL value it signifies that an
577 The return value must be a pointer to a static character string
578 containing an error message,
579 unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and
580 \fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is
581 either a dynamic string (to be released with \fBckfree\fR) or a
582 Tcl_Obj* (cast to char* and to be released with
583 \fBTcl_DecrRefCount\fR) containing the error message.
584 If a trace procedure returns an error, no further traces are
585 invoked for the access and the traced access aborts with the
587 Trace procedures can use this facility to make variables
588 read-only, for example (but note that the value of the variable
589 will already have been modified before the trace procedure is
590 called, so the trace procedure will have to restore the correct
593 The return value from \fIproc\fR is only used during read and
595 During unset traces, the return value is ignored and all relevant
596 trace procedures will always be invoked.
599 A trace procedure can be called at any time, even when there
600 is a partially formed result in the interpreter's result area. If
601 the trace procedure does anything that could damage this result (such
602 as calling \fBTcl_Eval\fR) then it must save the original values of
603 the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore
604 them before it returns.
605 .SH "UNDEFINED VARIABLES"
607 It is legal to set a trace on an undefined variable.
608 The variable will still appear to be undefined until the
609 first time its value is set.
610 If an undefined variable is traced and then unset, the unset will fail
612 .PQ "no such variable" "" ,
613 but the trace procedure will still be invoked.
614 .SH "TCL_TRACE_DESTROYED FLAG"
616 In an unset callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
617 is set in \fIflags\fR if the trace is being removed as part
619 Traces on a variable are always removed whenever the variable
620 is deleted; the only time \fBTCL_TRACE_DESTROYED\fR is not set is for
621 a whole-array trace invoked when only a single element of an
623 .SH "TCL_INTERP_DESTROYED"
625 When an interpreter is destroyed, unset traces are called for
626 all of its variables.
627 The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
628 argument passed to the trace procedures.
629 Trace procedures must be extremely careful in what they do if
630 the \fBTCL_INTERP_DESTROYED\fR bit is set.
631 It is not safe for the procedures to invoke any Tcl procedures
632 on the interpreter, since its state is partially deleted.
633 All that trace procedures should do under these circumstances is
634 to clean up and free their own internal data structures.
637 Tcl does not do any error checking to prevent trace procedures
638 from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
641 Array traces are not yet integrated with the Tcl \fBinfo exists\fR command,
642 nor is there Tcl-level access to array traces.
646 clientData, trace, variable
OSDN Git Service
