TraceVar man page on UnixWare

Man page or keyword search:  
man Server   3616 pages
apropos Keyword Search (all sections)
Output format
UnixWare 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.

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

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

       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.

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

       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
       interp->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_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.

       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_TRACE_DESTROYED will be set in
       flags if the trace is about to be destroyed;  this information  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  bit	 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 corre‐
       sponds 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 correspond
       to the next matching trace after the one whose clientData matches  pre‐
       vClientData, 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.   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).

       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 UnixWare

List of man pages available for UnixWare

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