trace man page on CentOS

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

trace(n)		     Tcl Built-In Commands		      trace(n)

______________________________________________________________________________

NAME
       trace  -	 Monitor  variable accesses, command usages and command execu‐
       tions

SYNOPSIS
       trace option ?arg arg ...?
_________________________________________________________________

DESCRIPTION
       This command causes Tcl commands to be executed whenever certain opera‐
       tions are invoked.  The legal option's (which may be abbreviated) are:

       trace add type name ops ?args?
	      Where type is command, execution, or variable.

	      trace add command name ops command
		     Arrange  for command to be executed whenever command name
		     is modified in one of the ways given  by  the  list  ops.
		     Name  will	 be resolved using the usual namespace resolu‐
		     tion rules used by procedures.  If the command  does  not
		     exist, an error will be thrown.

		     Ops  indicates which operations are of interest, and is a
		     list of one or more of the following items:

		     rename Invoke command whenever the	 command  is  renamed.
			    Note  that renaming to the empty string is consid‐
			    ered  deletion,  and  will	not  be	 traced	  with
			    'rename'.

		     delete Invoke  command when the command is deleted.  Com‐
			    mands can  be  deleted  explicitly	by  using  the
			    rename  command  to rename the command to an empty
			    string.  Commands are also deleted when the inter‐
			    preter  is deleted, but traces will not be invoked
			    because there is no interpreter in which  to  exe‐
			    cute them.

		     When  the	trace  triggers,  depending  on the operations
		     being traced, a number of arguments are appended to  com‐
		     mand so that the actual command is as follows:
			    command oldName newName op
		     OldName  and  newName  give  the traced command's current
		     (old) name, and the name to which	it  is	being  renamed
		     (the  empty  string if this is a 'delete' operation).  Op
		     indicates what operation is being performed on  the  com‐
		     mand,  and	 is  one of rename or delete as defined above.
		     The trace operation cannot be used to stop a command from
		     being  deleted.   Tcl will always remove the command once
		     the trace is complete.  Recursive	renaming  or  deleting
		     will  not	cause  further	traces	of the same type to be
		     evaluated, so a delete trace  which  itself  deletes  the
		     command,  or a rename trace which itself renames the com‐
		     mand will not cause further trace evaluations  to	occur.
		     Both  oldName  and	 newName  are fully qualified with any
		     namespace(s) in which they appear.

	      trace add execution name ops command
		     Arrange for command to be executed whenever command  name
		     is	 executed,  with  traces occurring at the points indi‐
		     cated by the list ops.  Name will be resolved  using  the
		     usual  namespace resolution rules used by procedures.  If
		     the command does not exist, an error will be thrown.

		     Ops indicates which operations are of interest, and is  a
		     list of one or more of the following items:

		     enter  Invoke  command  whenever the command name is exe‐
			    cuted, just	 before	 the  actual  execution	 takes
			    place.

		     leave  Invoke  command  whenever the command name is exe‐
			    cuted,  just  after	 the  actual  execution	 takes
			    place.

		     enterstep
			    Invoke command for every Tcl command which is exe‐
			    cuted inside the procedure name, just  before  the
			    actual  execution  takes place.  For example if we
			    have 'proc foo {}  {  puts	"hello"	 }',  then  an
			    enterstep  trace would be invoked just before puts
			    "hello" is executed.  Setting an  enterstep	 trace
			    on	a  command  will not result in an error and is
			    simply ignored.

		     leavestep
			    Invoke command for every Tcl command which is exe‐
			    cuted  inside  the	procedure name, just after the
			    actual execution takes place.  Setting a leavestep
			    trace on a command will not result in an error and
			    is simply ignored.

		     When the trace  triggers,	depending  on  the  operations
		     being  traced, a number of arguments are appended to com‐
		     mand so that the actual command is as follows:

		     For enter and enterstep operations:
			    command command-string op
		     Command-string gives the complete current	command	 being
		     executed  (the  traced  command for a enter operation, an
		     arbitrary command for a enterstep	operation),  including
		     all arguments in their fully expanded form.  Op indicates
		     what operation is being performed on the  command	execu‐
		     tion,  and is one of enter or enterstep as defined above.
		     The trace operation can be used to stop the command  from
		     executing,	 by  deleting  the  command  in	 question.  Of
		     course when the  command  is  subsequently	 executed,  an
		     'invalid command' error will occur.

		     For leave and leavestep operations:
			    command command-string code result op
		     Command-string  gives  the complete current command being
		     executed (the traced command for a	 enter	operation,  an
		     arbitrary	command	 for a enterstep operation), including
		     all arguments in their fully expanded form.   Code	 gives
		     the  result code of that execution, and result the result
		     string.  Op indicates what operation is  being  performed
		     on	 the  command  execution,  and	is  one	 of  leave  or
		     leavestep as defined above.  Note that  the  creation  of
		     many  enterstep  or  leavestep traces can lead to unintu‐
		     itive results, since the invoked commands from one	 trace
		     can  themselves  lead  to further command invocations for
		     other traces.

		     Command executes in the same context  as  the  code  that
		     invoked  the  traced  operation:  thus  the  command,  if
		     invoked from a procedure, will have access	 to  the  same
		     local  variables  as code in the procedure.  This context
		     may be different than the context in which the trace  was
		     created.  If  command  invokes a procedure (which it nor‐
		     mally does) then the procedure will have to use upvar  or
		     uplevel  commands	if it wishes to access the local vari‐
		     ables of the code which invoked the trace operation.

		     While command is executing	 during	 an  execution	trace,
		     traces  on name are temporarily disabled. This allows the
		     command to execute name in its body without invoking  any
		     other  traces  again.  If an error occurs while executing
		     the command body, then the command name as a  whole  will
		     return that same error.

		     When  multiple traces are set on name, then for enter and
		     enterstep operations, the traced commands are invoked  in
		     the  reverse order of how the traces were originally cre‐
		     ated; and for leave and leavestep operations, the	traced
		     commands are invoked in the original order of creation.

		     The  behavior  of execution traces is currently undefined
		     for a command name imported into another namespace.

	      trace add variable name ops command
		     Arrange for command to be executed whenever variable name
		     is	 accessed  in  one  of the ways given by the list ops.
		     Name may refer to a normal variable,  an  element	of  an
		     array,  or	 to an array as a whole (i.e. name may be just
		     the name of an array, with no parenthesized  index).   If
		     name  refers  to  a  whole array, then command is invoked
		     whenever any element of the array is manipulated.	If the
		     variable  does not exist, it will be created but will not
		     be given a value, so it  will  be	visible	 to  namespace
		     which queries, but not to info exists queries.

		     Ops  indicates which operations are of interest, and is a
		     list of one or more of the following items:

		     array  Invoke command whenever the variable  is  accessed
			    or	modified  via the array command, provided that
			    name is not a scalar variable at the time that the
			    array  command  is	invoked.   If name is a scalar
			    variable, the access via the  array	 command  will
			    not trigger the trace.

		     read   Invoke command whenever the variable is read.

		     write  Invoke command whenever the variable is written.

		     unset  Invoke  command  whenever  the  variable is unset.
			    Variables can be unset explicitly with  the	 unset
			    command, or implicitly when procedures return (all
			    of their local variables  are  unset).   Variables
			    are	 also unset when interpreters are deleted, but
			    traces will not be invoked	because	 there	is  no
			    interpreter in which to execute them.

		     When  the trace triggers, three arguments are appended to
		     command so that the actual command is as follows:
			    command name1 name2 op
		     Name1 and name2 give the name(s) for the  variable	 being
		     accessed:	 if  the variable is a scalar then name1 gives
		     the variable's name and name2 is an empty string; if  the
		     variable is an array element then name1 gives the name of
		     the array and name2 gives the index into the array; if an
		     entire  array  is	being deleted and the trace was regis‐
		     tered on the overall array, rather than a single element,
		     then  name1  gives	 the  array name and name2 is an empty
		     string.  Name1 and name2 are not necessarily the same  as
		     the  name	used in the trace variable command:  the upvar
		     command allows a procedure to reference a variable	 under
		     a	different  name.  Op indicates what operation is being
		     performed on the variable, and is one of read, write,  or
		     unset as defined above.

		     Command  executes	in  the	 same context as the code that
		     invoked  the  traced  operation:	if  the	 variable  was
		     accessed  as  part	 of a Tcl procedure, then command will
		     have access to the same local variables as	 code  in  the
		     procedure.	  This	context may be different than the con‐
		     text in which the trace was created. If command invokes a
		     procedure	(which	it  normally  does) then the procedure
		     will have to use upvar or uplevel if it wishes to	access
		     the traced variable.  Note also that name1 may not neces‐
		     sarily be the same as the name used to set the  trace  on
		     the variable; differences can occur if the access is made
		     through a variable defined with the upvar command.

		     For read and write traces, command can modify  the	 vari‐
		     able  to  affect  the result of the traced operation.  If
		     command modifies the value of a variable during a read or
		     write  trace,  then the new value will be returned as the
		     result of the traced operation.  The  return  value  from
		     command  is ignored except that if it returns an error of
		     any sort then the traced operation also returns an	 error
		     with the same error message returned by the trace command
		     (this mechanism can be used to implement read-only	 vari‐
		     ables,  for  example).   For  write  traces,  command  is
		     invoked after the variable's value has been  changed;  it
		     can  write	 a new value into the variable to override the
		     original value specified  in  the	write  operation.   To
		     implement	read-only  variables,  command	will  have  to
		     restore the old value of the variable.

		     While command is executing during a read or write	trace,
		     traces  on	 the  variable are temporarily disabled.  This
		     means that reads and writes invoked by command will occur
		     directly,	without invoking command (or any other traces)
		     again.  However, if  command  unsets  the	variable  then
		     unset traces will be invoked.

		     When  an unset trace is invoked, the variable has already
		     been deleted: it will appear  to  be  undefined  with  no
		     traces.   If  an  unset  occurs  because  of  a procedure
		     return, then the trace will be invoked  in	 the  variable
		     context  of  the  procedure being returned to:  the stack
		     frame of the returning procedure will  no	longer	exist.
		     Traces  are  not  disabled	 during unset traces, so if an
		     unset trace command creates a new trace and accesses  the
		     variable, the trace will be invoked.  Any errors in unset
		     traces are ignored.

		     If there are multiple  traces  on	a  variable  they  are
		     invoked  in order of creation, most-recent first.	If one
		     trace returns  an	error,	then  no  further  traces  are
		     invoked  for  the	variable.   If	an array element has a
		     trace set, and there is also a trace set on the array  as
		     a whole, the trace on the overall array is invoked before
		     the one on the element.

		     Once created, the trace remains in	 effect	 either	 until
		     the  trace is removed with the trace remove variable com‐
		     mand described below, until the  variable	is  unset,  or
		     until  the	 interpreter is deleted.  Unsetting an element
		     of array will remove any traces on that element, but will
		     not remove traces on the overall array.

		     This command returns an empty string.

       trace remove type name opList command
	      Where type is either command, execution or variable.

	      trace remove command name opList command
		     If	 there	is a trace set on command name with the opera‐
		     tions and command given by opList and command,  then  the
		     trace  is	removed,  so  that command will never again be
		     invoked.  Returns an  empty  string.    If	 name  doesn't
		     exist, the command will throw an error.

	      trace remove execution name opList command
		     If	 there	is a trace set on command name with the opera‐
		     tions and command given by opList and command,  then  the
		     trace  is	removed,  so  that command will never again be
		     invoked.  Returns an  empty  string.    If	 name  doesn't
		     exist, the command will throw an error.

	      trace remove variable name opList command
		     If	 there is a trace set on variable name with the opera‐
		     tions and command given by opList and command,  then  the
		     trace  is	removed,  so  that command will never again be
		     invoked.  Returns an empty string.

       trace info type name
	      Where type is either command, execution or variable.

	      trace info command name
		     Returns a list containing one element for each trace cur‐
		     rently  set  on command name. Each element of the list is
		     itself a list containing  two  elements,  which  are  the
		     opList  and  command  associated with the trace.  If name
		     doesn't have any traces set, then the result of the  com‐
		     mand will be an empty string.  If name doesn't exist, the
		     command will throw an error.

	      trace info execution name
		     Returns a list containing one element for each trace cur‐
		     rently  set  on command name. Each element of the list is
		     itself a list containing  two  elements,  which  are  the
		     opList  and  command  associated with the trace.  If name
		     doesn't have any traces set, then the result of the  com‐
		     mand will be an empty string.  If name doesn't exist, the
		     command will throw an error.

	      trace info variable name
		     Returns a list containing one element for each trace cur‐
		     rently set on variable name.  Each element of the list is
		     itself a list containing  two  elements,  which  are  the
		     opList  and  command  associated with the trace.  If name
		     doesn't exist or doesn't have any traces  set,  then  the
		     result of the command will be an empty string.

       For backwards compatibility, three other subcommands are available:

	      trace variable name ops command
		     This  is  equivalent  to trace add variable name ops com‐
		     mand.

	      trace vdelete name ops command
		     This is equivalent to trace remove variable name ops com‐
		     mand

	      trace vinfo name
		     This is equivalent to trace info variable name

       These subcommands are deprecated and will likely be removed in a future
       version of Tcl.	They use an older syntax in which array, read,	write,
       unset  are replaced by a, r, w and u respectively, and the ops argument
       is not a list, but simply a string  concatenation  of  the  operations,
       such as rwua.

EXAMPLES
       Print a message whenever either of the global variables foo and bar are
       updated, even if they have a different local name at  the  time	(which
       can be done with the upvar command):
	      proc tracer {varname args} {
		  upvar #0 $varname var
		  puts "$varname was updated to be \"$var\""
	      }
	      trace add variable foo write "tracer foo"
	      trace add variable bar write "tracer bar"

       Ensure  that  the global variable foobar always contains the product of
       the global variables foo and bar:
	      proc doMult args {
		  global foo bar foobar
		  set foobar [expr {$foo * $bar}]
	      }
	      trace add variable foo write doMult
	      trace add variable bar write doMult

SEE ALSO
       set(n), unset(n)

KEYWORDS
       read, command, rename, variable, write, trace, unset

Tcl				      8.4			      trace(n)
[top]

List of man pages available for CentOS

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