trace man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux 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 options (which may be abbreviated) are:

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

	      trace add command name ops commandPrefix
		     Arrange for commandPrefix to be executed (with additional
		     arguments) whenever command name is modified  in  one  of
		     the  ways	given  by  the list ops. Name will be resolved
		     using the usual namespace resolution rules used  by  com‐
		     mands.  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  commandPrefix  whenever the traced command
			    is renamed.	  Note	that  renaming	to  the	 empty
			    string  is	considered  deletion,  and will not be
			    traced with “rename”.

		     delete Invoke commandPrefix when the  traced  command  is
			    deleted.  Commands	can  be	 deleted explicitly by
			    using the rename command to rename the command  to
			    an	empty  string.	Commands are also deleted when
			    the interpreter is deleted, but traces will not be
			    invoked  because  there is no interpreter in which
			    to execute them.

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

			    commandPrefix 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 commandPrefix
		     Arrange for commandPrefix to be executed (with additional
		     arguments) whenever command name is executed, with traces
		     occurring	at the points indicated by the list ops.  Name
		     will be resolved using  the  usual	 namespace  resolution
		     rules  used  by commands.	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  commandPrefix whenever the command name is
			    executed, just before the actual  execution	 takes
			    place.

		     leave  Invoke  commandPrefix whenever the command name is
			    executed, just after the  actual  execution	 takes
			    place.

		     enterstep
			    Invoke  commandPrefix  for every Tcl command which
			    is executed from the start of the execution of the
			    procedure name until that procedure finishes. Com‐
			    mandPrefix is invoked just before the actual  exe‐
			    cution  of	the  Tcl  command being reported 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 name that
			    does not refer to a procedure will not  result  in
			    an error and is simply ignored.

		     leavestep
			    Invoke  commandPrefix  for every Tcl command which
			    is executed from the start of the execution of the
			    procedure name until that procedure finishes. Com‐
			    mandPrefix is invoked just after the actual execu‐
			    tion  of  the  Tcl	command	 being	reported takes
			    place.  Setting a leavestep	 trace	on  a  command
			    name  that	does not refer to a procedure 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‐
		     mandPrefix so that the actual command is as follows:

		     For enter and enterstep operations:

			    commandPrefix 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:

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

		     CommandPrefix executes in the same context	 as  the  code
		     that  invoked  the traced operation: thus the commandPre‐
		     fix, if invoked from a procedure, will have access to the
		     same  local variables as code in the procedure. This con‐
		     text may be different than the context in which the trace
		     was  created. If commandPrefix invokes a procedure (which
		     it normally does) then the procedure  will	 have  to  use
		     upvar  or	uplevel	 commands  if  it wishes to access the
		     local variables of the code which invoked the trace oper‐
		     ation.

		     While  commandPrefix  is  executing  during  an execution
		     trace, traces on  name  are  temporarily  disabled.  This
		     allows  the  commandPrefix	 to  execute  name in its body
		     without invoking any other traces	again.	 If  an	 error
		     occurs  while  executing the commandPrefix, then the com‐
		     mand 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 commandPrefix
		     Arrange  for  commandPrefix to be executed whenever vari‐
		     able name is accessed in one of the  ways	given  by  the
		     list  ops.	  Name may refer to a normal variable, an ele‐
		     ment 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‐
		     Prefix  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 vis‐
		     ible 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  commandPrefix  whenever  the  variable  is
			    accessed  or  modified via the array command, pro‐
			    vided 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  commandPrefix  whenever  the  variable  is
			    read.

		     write  Invoke  commandPrefix  whenever  the  variable  is
			    written.

		     unset  Invoke  commandPrefix  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
		     commandPrefix so that the actual command is as follows:

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

		     CommandPrefix  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 commandPrefix
		     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	 commandPrefix
		     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 necessarily 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, commandPrefix can modify the
		     variable to affect the result of  the  traced  operation.
		     If	 commandPrefix 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	commandPrefix is ignored  except  that
		     if it returns an error of any sort then the traced opera‐
		     tion also returns an error with the  same	error  message
		     returned by the trace command (this mechanism can be used
		     to implement  read-only  variables,  for  example).   For
		     write  traces,  commandPrefix  is invoked after the vari‐
		     able's value has been changed; it can write a  new	 value
		     into  the	variable to override the original value speci‐
		     fied in the  write	 operation.   To  implement  read-only
		     variables,	 commandPrefix	will  have  to restore the old
		     value of the variable.

		     While commandPrefix is executing during a read  or	 write
		     trace,  traces  on the variable are temporarily disabled.
		     This means that reads and writes invoked by commandPrefix
		     will  occur  directly, without invoking commandPrefix (or
		     any  other	 traces)  again.   However,  if	 commandPrefix
		     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 commandPrefix
	      Where type is either command, execution or variable.

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

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

	      trace remove variable name opList commandPrefix
		     If	 there is a trace set on variable name with the opera‐
		     tions and command given by opList and commandPrefix, then
		     the  trace	 is  removed, so that commandPrefix 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  commandPrefix associated with the trace.  If
		     name does not have any traces set, then the result of the
		     command will be an empty string.  If name does not 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  commandPrefix associated with the trace.  If
		     name does not have any traces set, then the result of the
		     command will be an empty string.  If name does not 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  commandPrefix associated with the trace.  If
		     name does not exist or does not 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

       Print a trace of what commands are executed during the processing of  a
       Tcl procedure:

	      proc x {} { y }
	      proc y {} { z }
	      proc z {} { puts hello }
	      proc report args {puts [info level 0]}
	      trace add execution x enterstep report
	      x
		→ report y enterstep
		  report z enterstep
		  report {puts hello} enterstep
		  hello

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 Archlinux

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