Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 us-
		     ing 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 us-
			    ing	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 in-
			    voked  because there is no interpreter in which to
			    execute them.

		     When the trace triggers, depending	on the operations  be-
		     ing  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 in-
			    voked 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  be-
		     ing  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 "in-
		     valid 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 up-
		     var  or uplevel commands if it wishes to access the local
		     variables of the code which invoked the trace operation.

		     While commandPrefix  is  executing	 during	 an  execution
		     trace,  traces on name are	temporarily disabled. This al-
		     lows the commandPrefix to execute name in its body	 with-
		     out  invoking any other traces again.  If an error	occurs
		     while executing the commandPrefix,	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 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 ac-
			    cessed 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  commandPrefix  whenever  the  variable  is
			    read.

		     write  Invoke  commandPrefix  whenever  the  variable  is
			    written.

		     unset  Invoke commandPrefix whenever the variable is  un-
			    set.   Variables  can be unset explicitly with the
			    unset command, or implicitly when  procedures  re-
			    turn  (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  ac-
		     cess  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 re-
		     turned 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  operation
		     also  returns  an	error  with the	same error message re-
		     turned 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 un-
		     sets 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  re-
		     turn, then	the trace will be invoked in the variable con-
		     text 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 vari-
		     able, the trace will be invoked.	Any  errors  in	 unset
		     traces are	ignored.

		     If	 there	are multiple traces on a variable they are in-
		     voked in order of creation, most-recent  first.   If  one
		     trace  returns  an	 error,	then no	further	traces are in-
		     voked 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 un-
		     til 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)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=trace.tcl86&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help