diff options
Diffstat (limited to 'contrib/tcl/doc/TraceVar.3')
| -rw-r--r-- | contrib/tcl/doc/TraceVar.3 | 348 |
1 files changed, 0 insertions, 348 deletions
diff --git a/contrib/tcl/doc/TraceVar.3 b/contrib/tcl/doc/TraceVar.3 deleted file mode 100644 index 976be4f212de..000000000000 --- a/contrib/tcl/doc/TraceVar.3 +++ /dev/null @@ -1,348 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" SCCS: @(#) TraceVar.3 1.27 97/10/10 15:05:37 -'\" -.so man.macros -.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_TraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR -.sp -int -\fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR -.sp -\fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR -.sp -\fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR -.sp -ClientData -\fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR -.sp -ClientData -\fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR -.SH ARGUMENTS -.AS Tcl_VarTraceProc prevClientData -.AP Tcl_Interp *interp in -Interpreter containing variable. -.AP char *varName in -Name of variable. May refer to a scalar variable, to -an array variable with no index, or to an array variable -with a parenthesized index. -If the name references an element of an array, then it -must be in writable memory: Tcl will make temporary modifications -to it while looking up the name. -.AP int flags in -OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and -TCL_TRACE_UNSETS, TCL_PARSE_PART1, and TCL_GLOBAL_ONLY. -Not all flags are used by all -procedures. See below for more information. -.AP Tcl_VarTraceProc *proc in -Procedure to invoke whenever one of the traced operations occurs. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.AP char *name1 in -Name of scalar or array variable (without array index). -.AP char *name2 in -For a trace on an element of an array, gives the index of the -element. For traces on scalar variables or on whole arrays, -is NULL. -.AP ClientData prevClientData in -If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or -\fBTcl_VarTraceInfo2\fR, so this call will return information about -next trace. If NULL, this call will return information about first -trace. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_TraceVar\fR allows a C procedure to monitor and control -access to a Tcl variable, so that the C procedure is invoked -whenever the variable is read or written or unset. -If the trace is created successfully then \fBTcl_TraceVar\fR returns -TCL_OK. If an error occurred (e.g. \fIvarName\fR specifies an element -of an array, but the actual variable isn't an array) then TCL_ERROR -is returned and an error message is left in \fIinterp->result\fR. -.PP -The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the -trace procedure is to be invoked and provides information -for setting up the trace. It consists of an OR-ed combination -of any of the following values: -.TP -\fBTCL_GLOBAL_ONLY\fR -Normally, the variable will be looked up at the current level of -procedure call; if this bit is set then the variable will be looked -up at global level, ignoring any active procedures. -.TP -\fBTCL_TRACE_READS\fR -Invoke \fIproc\fR whenever an attempt is made to read the variable. -.TP -\fBTCL_TRACE_WRITES\fR -Invoke \fIproc\fR whenever an attempt is made to modify the variable. -.TP -\fBTCL_TRACE_UNSETS\fR -Invoke \fIproc\fR whenever the variable is unset. -A variable may be unset either explicitly by an \fBunset\fR command, -or implicitly when a procedure returns (its local variables are -automatically unset) or when the interpreter is deleted (all -variables are automatically unset). -.PP -Whenever one of the specified operations occurs on the variable, -\fIproc\fR will be invoked. -It should have arguments and result that match the type -\fBTcl_VarTraceProc\fR: -.CS -typedef char *Tcl_VarTraceProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - char *\fIname1\fR, - char *\fIname2\fR, - int \fIflags\fR); -.CE -The \fIclientData\fR and \fIinterp\fR parameters will -have the same values as those passed to \fBTcl_TraceVar\fR when the -trace was created. -\fIClientData\fR typically points to an application-specific -data structure that describes what to do when \fIproc\fR -is invoked. -\fIName1\fR and \fIname2\fR give the name of the traced variable -in the normal two-part form (see the description of \fBTcl_TraceVar2\fR -below for details). -\fIFlags\fR is an OR-ed combination of bits providing several -pieces of information. -One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, or TCL_TRACE_UNSETS -will be set in \fIflags\fR to indicate which operation is being performed -on the variable. -The bit TCL_GLOBAL_ONLY will be set whenever the variable being -accessed is a global one not accessible from the current level of -procedure call: the trace procedure will need to pass this flag -back to variable-related procedures like \fBTcl_GetVar\fR if it -attempts to access the variable. -The bit TCL_TRACE_DESTROYED will be set in \fIflags\fR if the trace is -about to be destroyed; this information may be useful to \fIproc\fR -so that it can clean up its own internal data structures (see -the section TCL_TRACE_DESTROYED below for more details). -Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire -interpreter is being destroyed. -When this bit is set, \fIproc\fR must be especially careful in -the things it does (see the section TCL_INTERP_DESTROYED below). -The trace procedure's return value should normally be NULL; see -ERROR RETURNS below for information on other possibilities. -.PP -\fBTcl_UntraceVar\fR may be used to remove a trace. -If the variable specified by \fIinterp\fR, \fIvarName\fR, and \fIflags\fR -has a trace set with \fIflags\fR, \fIproc\fR, and -\fIclientData\fR, then the corresponding trace is removed. -If no such trace exists, then the call to \fBTcl_UntraceVar\fR -has no effect. -The same bits are valid for \fIflags\fR as for calls to \fBTcl_TraceVar\fR. -.PP -\fBTcl_VarTraceInfo\fR may be used to retrieve information about -traces set on a given variable. -The return value from \fBTcl_VarTraceInfo\fR is the \fIclientData\fR -associated with a particular trace. -The trace must be on the variable specified by the \fIinterp\fR, -\fIvarName\fR, and \fIflags\fR arguments (only the TCL_GLOBAL_ONLY -bit from \fIflags\fR is used; other bits are ignored) and its trace procedure -must the same as the \fIproc\fR argument. -If the \fIprevClientData\fR argument is NULL then the return -value corresponds to the first (most recently created) matching -trace, or NULL if there are no matching traces. -If the \fIprevClientData\fR argument isn't NULL, then it should -be the return value from a previous call to \fBTcl_VarTraceInfo\fR. -In this case, the new return value will correspond to the next -matching trace after the one whose \fIclientData\fR matches -\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR -or if there are no more matching traces after it. -This mechanism makes it possible to step through all of the -traces for a given variable that have the same \fIproc\fR. - -.SH "TWO-PART NAMES" -.PP -The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and -\fBTcl_VarTraceInfo2\fR are identical to \fBTcl_TraceVar\fR, -\fBTcl_UntraceVar\fR, and \fBTcl_VarTraceInfo\fR, respectively, -except that the name of the variable consists of two parts. -\fIName1\fR gives the name of a scalar variable or array, -and \fIname2\fR gives the name of an element within an array. -If \fIname2\fR is NULL it means that either the variable is -a scalar or the trace is to be set on the entire array rather -than an individual element (see WHOLE-ARRAY TRACES below for -more information). -As a special case, if the flag TCL_PARSE_PART1 is specified, -\fIname1\fR may contain both an array and an element name: -if the name contains an open parenthesis and ends with a -close parenthesis, then the value between the parentheses is -treated as an element name (which can have any string value) and -the characters before the first open -parenthesis are treated as the name of an array variable. -If the flag TCL_PARSE_PART1 is given, -\fIname2\fR should be NULL since the array and element names -are taken from \fIname1\fR. - -.SH "ACCESSING VARIABLES DURING TRACES" -.PP -During read and write traces, the -trace procedure can read, write, or unset the traced -variable using \fBTcl_GetVar2\fR, \fBTcl_SetVar2\fR, and -other procedures. -While \fIproc\fR is executing, traces are temporarily disabled -for the variable, so that calls to \fBTcl_GetVar2\fR and -\fBTcl_SetVar2\fR will not cause \fIproc\fR or other trace procedures -to be invoked again. -Disabling only occurs for the variable whose trace procedure -is active; accesses to other variables will still be traced. -However, if a variable is unset during a read or write trace then unset -traces will be invoked. -.PP -During unset traces the variable has already been completely -expunged. -It is possible for the trace procedure to read or write the -variable, but this will be a new version of the variable. -Traces are not disabled during unset traces as they are for -read and write traces, but existing traces have been removed -from the variable before any trace procedures are invoked. -If new traces are set by unset trace procedures, these traces -will be invoked on accesses to the variable by the trace -procedures. - -.SH "CALLBACK TIMING" -.PP -When read tracing has been specified for a variable, the trace -procedure will be invoked whenever the variable's value is -read. This includes \fBset\fR Tcl commands, \fB$\fR-notation -in Tcl commands, and invocations of the \fBTcl_GetVar\fR -and \fBTcl_GetVar2\fR procedures. -\fIProc\fR is invoked just before the variable's value is -returned. -It may modify the value of the variable to affect what -is returned by the traced access. -If it unsets the variable then the access will return an error -just as if the variable never existed. -.PP -When write tracing has been specified for a variable, the -trace procedure will be invoked whenever the variable's value -is modified. This includes \fBset\fR commands, -commands that modify variables as side effects (such as -\fBcatch\fR and \fBscan\fR), and calls to the \fBTcl_SetVar\fR -and \fBTcl_SetVar2\fR procedures). -\fIProc\fR will be invoked after the variable's value has been -modified, but before the new value of the variable has been -returned. -It may modify the value of the variable to override the change -and to determine the value actually returned by the traced -access. -If it deletes the variable then the traced access will return -an empty string. -.PP -When unset tracing has been specified, the trace procedure -will be invoked whenever the variable is destroyed. -The traces will be called after the variable has been -completely unset. - -.SH "WHOLE-ARRAY TRACES" -.PP -If a call to \fBTcl_TraceVar\fR or \fBTcl_TraceVar2\fR specifies -the name of an array variable without an index into the array, -then the trace will be set on the array as a whole. -This means that \fIproc\fR will be invoked whenever any -element of the array is accessed in the ways specified by -\fIflags\fR. -When an array is unset, a whole-array trace will be invoked -just once, with \fIname1\fR equal to the name of the array -and \fIname2\fR NULL; it will not be invoked once for each -element. - -.SH "MULTIPLE TRACES" -.PP -It is possible for multiple traces to exist on the same variable. -When this happens, all of the trace procedures will be invoked on each -access, in order from most-recently-created to least-recently-created. -When there exist whole-array traces for an array as well as -traces on individual elements, the whole-array traces are invoked -before the individual-element traces. -If a read or write trace unsets the variable then all of the unset -traces will be invoked but the remainder of the read and write traces -will be skipped. - -.SH "ERROR RETURNS" -.PP -Under normal conditions trace procedures should return NULL, indicating -successful completion. -If \fIproc\fR returns a non-NULL value it signifies that an -error occurred. -The return value must be a pointer to a static character string -containing an error message. -If a trace procedure returns an error, no further traces are -invoked for the access and the traced access aborts with the -given message. -Trace procedures can use this facility to make variables -read-only, for example (but note that the value of the variable -will already have been modified before the trace procedure is -called, so the trace procedure will have to restore the correct -value). -.PP -The return value from \fIproc\fR is only used during read and -write tracing. -During unset traces, the return value is ignored and all relevant -trace procedures will always be invoked. - -.SH "RESTRICTIONS" -.PP -A trace procedure can be called at any time, even when there -is a partially-formed result in the interpreter's result area. If -the trace procedure does anything that could damage this result (such -as calling \fBTcl_Eval\fR) then it must save the original values of -the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore -them before it returns. - -.SH "UNDEFINED VARIABLES" -.PP -It is legal to set a trace on an undefined variable. -The variable will still appear to be undefined until the -first time its value is set. -If an undefined variable is traced and then unset, the unset will fail -with an error (``no such variable''), but the trace -procedure will still be invoked. - -.SH "TCL_TRACE_DESTROYED FLAG" -.PP -In an unset callback to \fIproc\fR, the TCL_TRACE_DESTROYED bit -is set in \fIflags\fR if the trace is being removed as part -of the deletion. -Traces on a variable are always removed whenever the variable -is deleted; the only time TCL_TRACE_DESTROYED isn't set is for -a whole-array trace invoked when only a single element of an -array is unset. - -.SH "TCL_INTERP_DESTROYED" -.PP -When an interpreter is destroyed, unset traces are called for -all of its variables. -The TCL_INTERP_DESTROYED bit will be set in the \fIflags\fR -argument passed to the trace procedures. -Trace procedures must be extremely careful in what they do if -the TCL_INTERP_DESTROYED bit is set. -It is not safe for the procedures to invoke any Tcl procedures -on the interpreter, since its state is partially deleted. -All that trace procedures should do under these circumstances is -to clean up and free their own internal data structures. - -.SH BUGS -.PP -Tcl doesn't do any error checking to prevent trace procedures -from misusing the interpreter during traces with TCL_INTERP_DESTROYED -set. - -.SH KEYWORDS -clientData, trace, variable |