new subtree for tcl/tk

1 files changed, 0 insertions, 380 deletions

diff --git a/tcl8.6/doc/TraceVar.3 b/tcl8.6/doc/TraceVar.3
deleted file mode 100644
index 19cb467..0000000
--- a/tcl8.6/doc/TraceVar.3
+++ /dev/null
@@ -1,380 +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.
-'\"
-.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
-.so man.macros
-.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 "const 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.
-.AP int flags in
-OR-ed combination of the values \fBTCL_TRACE_READS\fR,
-\fBTCL_TRACE_WRITES\fR, \fBTCL_TRACE_UNSETS\fR, \fBTCL_TRACE_ARRAY\fR,
-\fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR,
-\fBTCL_TRACE_RESULT_DYNAMIC\fR and \fBTCL_TRACE_RESULT_OBJECT\fR.
-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 "const char" *name1 in
-Name of scalar or array variable (without array index).
-.AP "const 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
-\fBTCL_OK\fR.  If an error occurred (e.g. \fIvarName\fR specifies an element
-of an array, but the actual variable is not an array) then \fBTCL_ERROR\fR
-is returned and an error message is left in the interpreter's result.
-.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_NAMESPACE_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 in the current namespace, 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).
-.TP
-\fBTCL_TRACE_ARRAY\fR
-Invoke \fIproc\fR whenever the array command is invoked.
-This gives the trace procedure a chance to update the array before
-array names or array get is called.  Note that this is called
-before an array set, but that will trigger write traces.
-.TP
-\fBTCL_TRACE_RESULT_DYNAMIC\fR
-The result of invoking the \fIproc\fR is a dynamically allocated
-string that will be released by the Tcl library via a call to
-\fBckfree\fR.  Must not be specified at the same time as
-\fBTCL_TRACE_RESULT_OBJECT\fR.
-.TP
-\fBTCL_TRACE_RESULT_OBJECT\fR
-The result of invoking the \fIproc\fR is a Tcl_Obj* (cast to a char*)
-with a reference count of at least one.  The ownership of that
-reference will be transferred to the Tcl core for release (when the
-core has finished with it) via a call to \fBTcl_DecrRefCount\fR.  Must
-not be specified at the same time as \fBTCL_TRACE_RESULT_DYNAMIC\fR.
-.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:
-.PP
-.CS
-typedef char *\fBTcl_VarTraceProc\fR(
-        ClientData \fIclientData\fR,
-        Tcl_Interp *\fIinterp\fR,
-        char *\fIname1\fR,
-        char *\fIname2\fR,
-        int \fIflags\fR);
-.CE
-.PP
-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 \fBTCL_TRACE_READS\fR, \fBTCL_TRACE_WRITES\fR,
-\fBTCL_TRACE_ARRAY\fR, or \fBTCL_TRACE_UNSETS\fR
-will be set in \fIflags\fR to indicate which operation is being performed
-on the variable.
-The bit \fBTCL_GLOBAL_ONLY\fR 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 \fBTCL_NAMESPACE_ONLY\fR will be set whenever the variable being
-accessed is a namespace 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 \fBTCL_TRACE_DESTROYED\fR 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 \fBTCL_TRACE_DESTROYED\fR below for more details).
-Lastly, the bit \fBTCL_INTERP_DESTROYED\fR 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 \fBTCL_INTERP_DESTROYED\fR below).
-The trace procedure's return value should normally be NULL;  see
-\fBERROR RETURNS\fR 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 \fBTCL_GLOBAL_ONLY\fR and
-\fBTCL_NAMESPACE_ONLY\fR bits 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 is not 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.
-When \fIname2\fR is NULL,
-\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 \fIname2\fR is NULL and \fIname1\fR does not refer
-to an array element 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).
-.SH "ACCESSING VARIABLES DURING TRACES"
-.PP
-During read, write, and array 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 array tracing has been specified, the trace procedure
-will be invoked at the beginning of the array command implementation,
-before any of the operations like get, set, or names have been invoked.
-The trace procedure can modify the array elements with \fBTcl_SetVar\fR
-and \fBTcl_SetVar2\fR.
-.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,
-unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and
-\fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is
-either a dynamic string (to be released with \fBckfree\fR) or a
-Tcl_Obj* (cast to char* and to be released with
-\fBTcl_DecrRefCount\fR) containing the 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
-.PQ "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 \fBTCL_TRACE_DESTROYED\fR 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 \fBTCL_TRACE_DESTROYED\fR is not 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 \fBTCL_INTERP_DESTROYED\fR 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 \fBTCL_INTERP_DESTROYED\fR 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 does not do any error checking to prevent trace procedures
-from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
-set.
-.PP
-Array traces are not yet integrated with the Tcl \fBinfo exists\fR command,
-nor is there Tcl-level access to array traces.
-.SH "SEE ALSO"
-trace(n)
-.SH KEYWORDS
-clientData, trace, variable