Tcl_VarTraceInfo man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

Tcl_TraceVar(3)		    Tcl Library Procedures	       Tcl_TraceVar(3)

______________________________________________________________________________

NAME
       Tcl_TraceVar,  Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_Var-
       TraceInfo, Tcl_VarTraceInfo2 - monitor accesses to a variable

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_TraceVar(interp, varName, flags, proc, clientData)

       int
       Tcl_TraceVar2(interp, name1, name2, flags, proc, clientData)

       Tcl_UntraceVar(interp, varName, flags, proc, clientData)

       Tcl_UntraceVar2(interp, name1, name2, flags, proc, clientData)

       ClientData
       Tcl_VarTraceInfo(interp, varName, flags, proc, prevClientData)

       ClientData
       Tcl_VarTraceInfo2(interp, name1, name2, flags, proc, prevClientData)

ARGUMENTS
       Tcl_Interp	  *interp	   (in)	     Interpreter    containing
						     variable.

       CONST char	  *varName	   (in)	     Name  of  variable.   May
						     refer to a	 scalar	 vari-
						     able,  to	an array vari-
						     able with no index, or to
						     an	 array variable with a
						     parenthesized index.

       int		  flags		   (in)	     OR-ed combination of  the
						     values   TCL_TRACE_READS,
						     TCL_TRACE_WRITES,
						     TCL_TRACE_UNSETS,
						     TCL_TRACE_ARRAY,
						     TCL_GLOBAL_ONLY,
						     TCL_NAMESPACE_ONLY,
						     TCL_TRACE_RESULT_DYNAMIC
						     and
						     TCL_TRACE_RESULT_OBJECT.
						     Not all flags are used by
						     all    procedures.	   See
						     below for	more  informa-
						     tion.

       Tcl_VarTraceProc	  *proc		   (in)	     Procedure to invoke when-
						     ever one  of  the	traced
						     operations occurs.

       ClientData	  clientData	   (in)	     Arbitrary	one-word value
						     to pass to proc.

       CONST char	  *name1	   (in)	     Name of scalar  or	 array
						     variable  (without	 array
						     index).

       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.

       ClientData	  prevClientData   (in)	     If	 non-NULL,  gives last
						     value     returned	    by
						     Tcl_VarTraceInfo	    or
						     Tcl_VarTraceInfo2,	    so
						     this   call  will	return
						     information  about	  next
						     trace.    If  NULL,  this
						     call will return informa-
						     tion about first trace.
_________________________________________________________________

DESCRIPTION
       Tcl_TraceVar  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
       Tcl_TraceVar returns TCL_OK.  If an error occurred (e.g. varName speci-
       fies  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  the	inter-
       preter's result.

       The  flags  argument to Tcl_TraceVar 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:

       TCL_GLOBAL_ONLY
	      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.

       TCL_NAMESPACE_ONLY
	      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 proce-
	      dures.

       TCL_TRACE_READS
	      Invoke proc whenever an attempt is made to read the variable.

       TCL_TRACE_WRITES
	      Invoke proc whenever an attempt is made to modify the  variable.

       TCL_TRACE_UNSETS
	      Invoke  proc  whenever the variable is unset.  A variable may be
	      unset either explicitly by an unset command, or implicitly  when
	      a	 procedure  returns  (its  local  variables  are automatically
	      unset) or when the interpreter is	 deleted  (all	variables  are
	      automatically unset).

       TCL_TRACE_ARRAY
	      Invoke  proc  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.		       |

       TCL_TRACE_RESULT_DYNAMIC						       ||
	      The  result  of  invoking	 the  proc  is a dynamically allocated |
	      string that will be released by the Tcl library via  a  call  to |
	      ckfree.	 Must	not   be   specified   at  the	same  time  as |
	      TCL_TRACE_RESULT_OBJECT.					       |

       TCL_TRACE_RESULT_OBJECT						       ||
	      The  result of invoking the proc 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  Tcl_DecrRefCount. |
	      Must    not    be	   specified	at    the    same    time   as |
	      TCL_TRACE_RESULT_DYNAMIC.

       Whenever one of the specified operations occurs on the  variable,  proc
       will  be	 invoked.   It should have arguments and result that match the
       type Tcl_VarTraceProc:
	      typedef char *Tcl_VarTraceProc(
		ClientData clientData,
		Tcl_Interp *interp,
		char *name1,
		char *name2,
		int flags);
       The clientData and interp parameters will have the same values as those
       passed  to  Tcl_TraceVar	 when the trace was created.  ClientData typi-
       cally points to an application-specific data structure  that  describes
       what  to do when proc is invoked.  Name1 and name2 give the name of the
       traced variable in the normal two-part form  (see  the  description  of
       Tcl_TraceVar2  below  for  details).   Flags is an OR-ed combination of
       bits  providing	several	 pieces	 of  information.   One	 of  the  bits
       TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_ARRAY, or TCL_TRACE_UNSETS
       will be set in flags to indicate which operation is being performed  on
       the  variable.	The bit TCL_GLOBAL_ONLY will be set whenever the vari-
       able 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 Tcl_GetVar if it attempts
       to  access  the variable.  The bit TCL_NAMESPACE_ONLY will be set when-
       ever 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	Tcl_GetVar  if
       it  attempts  to access the variable.  The bit TCL_TRACE_DESTROYED will
       be set in flags if the trace is about to be destroyed;	this  informa-
       tion  may  be  useful  to proc 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, proc 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.

       Tcl_UntraceVar may be used to remove a trace.  If the  variable	speci-
       fied  by	 interp,  varName, and flags has a trace set with flags, proc,
       and clientData, then the corresponding trace is removed.	  If  no  such
       trace  exists, then the call to Tcl_UntraceVar has no effect.  The same
       bits are valid for flags as for calls to Tcl_TraceVar.

       Tcl_VarTraceInfo may be used to retrieve information about  traces  set
       on  a  given  variable.	 The return value from Tcl_VarTraceInfo is the
       clientData associated with a particular trace.  The trace  must	be  on
       the  variable  specified	 by  the  interp, varName, and flags arguments
       (only the TCL_GLOBAL_ONLY and TCL_NAMESPACE_ONLY	 bits  from  flags  is
       used;  other bits are ignored) and its trace procedure must the same as
       the proc argument.  If the prevClientData 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	prevClientData
       argument isn't NULL, then it should be the return value from a previous
       call to Tcl_VarTraceInfo.  In this case, the new return value will cor-
       respond	to  the	 next  matching	 trace	after the one whose clientData
       matches prevClientData, or NULL if no trace matches  prevClientData  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 proc.

TWO-PART NAMES
       The  procedures	Tcl_TraceVar2,	Tcl_UntraceVar2, and Tcl_VarTraceInfo2
       are identical to Tcl_TraceVar,  Tcl_UntraceVar,	and  Tcl_VarTraceInfo,
       respectively,  except  that  the	 name  of the variable consists of two
       parts.  Name1 gives the name of a scalar variable or array,  and	 name2
       gives  the  name	 of  an	 element within an array.  When name2 is NULL, |
       name1 may contain both an array and an element name: if the  name  con- |
       tains  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 paren- |
       thesis are treated as the name of an array variable.  If name2 is  NULL |
       and  name1  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).

ACCESSING VARIABLES DURING TRACES
       During read, write, and array traces, the  trace	 procedure  can	 read,
       write, or unset the traced variable using Tcl_GetVar2, Tcl_SetVar2, and
       other procedures.  While proc is executing, traces are temporarily dis-
       abled  for  the	variable, so that calls to Tcl_GetVar2 and Tcl_SetVar2
       will not cause proc 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	 vari-
       able  is	 unset	during a read or write trace then unset traces will be
       invoked.

       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  dis-
       abled  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 proce-
       dures, these traces will be invoked on accesses to the variable by  the
       trace procedures.

CALLBACK TIMING
       When  read  tracing has been specified for a variable, the trace proce-
       dure will be invoked whenever  the  variable's  value  is  read.	  This
       includes	 set Tcl commands, $-notation in Tcl commands, and invocations
       of the Tcl_GetVar and Tcl_GetVar2 procedures.   Proc  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.

       When write tracing has been specified for a variable, the trace	proce-
       dure  will  be invoked whenever the variable's value is modified.  This
       includes set commands, commands that modify variables as	 side  effects
       (such  as  catch and scan), and calls to the Tcl_SetVar and Tcl_SetVar2
       procedures).  Proc 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.

       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  Tcl_SetVar  and
       Tcl_SetVar2.

       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.

WHOLE-ARRAY TRACES
       If  a  call  to	Tcl_TraceVar or Tcl_TraceVar2 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 proc will be invoked
       whenever any element of the array is accessed in the ways specified  by
       flags.	When  an  array	 is unset, a whole-array trace will be invoked
       just once, with name1 equal to the name of the array  and  name2	 NULL;
       it will not be invoked once for each element.

MULTIPLE TRACES
       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	 vari-
       able  then all of the unset traces will be invoked but the remainder of
       the read and write traces will be skipped.

ERROR RETURNS
       Under normal conditions trace procedures should return NULL, indicating
       successful  completion.	 If proc 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 (exactly one of) |
       the TCL_TRACE_RESULT_DYNAMIC and TCL_TRACE_RESULT_OBJECT flags is  set, |
       which  specify  that  the  result  is  either  a	 dynamic string (to be |
       released with ckfree) or a Tcl_Obj* (cast to char* and to  be  released |
       with Tcl_DecrRefCount) containing the error message.  If a trace proce-
       dure 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).

       The  return value from proc 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.

RESTRICTIONS
       A  trace procedure can be called at any time, even when there is a par-
       tially-formed result in the interpreter's result area.	If  the	 trace
       procedure  does anything that could damage this result (such as calling
       Tcl_Eval) then it must save the original values	of  the	 interpreter's
       result and freeProc fields and restore them before it returns.

UNDEFINED VARIABLES
       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.

TCL_TRACE_DESTROYED FLAG
       In  an  unset  callback	to proc, the TCL_TRACE_DESTROYED bit is set in
       flags 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.

TCL_INTERP_DESTROYED
       When  an	 interpreter  is destroyed, unset traces are called for all of
       its variables.  The TCL_INTERP_DESTROYED bit will be set in  the	 flags
       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.

BUGS
       Tcl doesn't do any error checking to prevent trace procedures from mis-
       using the interpreter during traces with TCL_INTERP_DESTROYED set.

       Array traces are not yet integrated with the Tcl "info exists" command,
       nor is there Tcl-level access to array traces.

KEYWORDS
       clientData, trace, variable

Tcl				      7.4		       Tcl_TraceVar(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net