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

FreeBSD Manual Pages

  
 
  

home | help
watch(n)		     BLT Built-In Commands		      watch(n)

______________________________________________________________________________

NAME
       watch - call Tcl	procedures before and after each command

SYNOPSIS
       watch create watchName ?options?

       watch activate watchName

       watch deactivate	watchName

       watch delete watchName

       watch configure watchName ?options

       watch info watchName

       watch names
_________________________________________________________________

DESCRIPTION
       The  watch command arranges for Tcl procedures to be invoked before and
       after the execution of each Tcl command.

INTRODUCTION
       When an error occurs in Tcl, the	global variable	errorInfo will contain
       a  stack-trace  of the active procedures	when the error occured.	 Some-
       times, however, the stack trace is insufficient.	 You may need to  know
       exactly	where  in the program's	execution the error occured.  In cases
       like this, a more general tracing facility would	be useful.

       The watch command lets you designate Tcl	procedures to be  invoked  be-
       fore  and  after	the execution of each Tcl command.  This means you can
       display the command line	and its	results	for each command  as  it  exe-
       cutes.	Another	 use is	to profile your	Tcl commands.  You can profile
       any Tcl command (like if	and set), not just Tcl procedures.

EXAMPLE
       The following example use watch to  trace  Tcl  commands	 (printing  to
       standard	error) both before and after they are executed.

	      proc preCmd { level command argv } {
		  set name [lindex $argv 0]
		  puts stderr "$level $name => $command"
	      }

	      proc postCmd { level command argv	retcode	results	} {
		  set name [lindex $argv 0]
		  puts stderr "$level $name => $argv0= ($retcode) $results"
	      }
	      watch create trace \
		-postcmd postCmd -precmd preCmd

OPERATIONS
       The following operations	are available for the watch command:

       watch activate watchName
	      Activates	 the  watch, causing Tcl commands the be traced	to the
	      maximum depth selected.

       watch create watchName ?options?...
	      Creates a	new watch watchName. It's an error  if	another	 watch
	      watchName	 already exists	and an error message will be returned.
	      Options may have any of the values accepted by the watch config-
	      ure command.  This command returns the empty string.

       watch configure watchName ?options...?
	      Queries  or  modifies  the  configuration	 options  of the watch
	      watchName.  WatchName is the name	of a watch.  Options may  have
	      any of the following values:

	      -active boolean
		     Specifies	if  the	 watch is active.  By default, watches
		     are active	when created.

	      -postcmd string
		     Specifies a Tcl procedure to be called immediately	 after
		     each  Tcl command.	 String	is name	of a Tcl procedure and
		     any extra arguments to be passed to it.  Before string is
		     invoked, five more	arguments are appended:	1) the current
		     level 2) the current command line 3)  a  list  containing
		     the  command  after substitutions and split into words 4)
		     the return	code of	the command, and 5) the	results	of the
		     command.	The  return status of the postcmd procedure is
		     always ignored.

	      -precmd string
		     Specifies a Tcl procedure to be called immediately	before
		     each  Tcl command.	 String	is name	of a Tcl procedure and
		     any extra arguments to be passed to it.  Before string is
		     invoked,  three  arguments	 are  appended:	1) the current
		     level 2) the current command line,	and 3) a list contain-
		     ing the command after substitutions and split into	words.
		     The return	status of the -precmd procedure	is always  ig-
		     nored.

	      -maxlevel	number
		     Specifies	the maximum evaluation depth to	watch Tcl com-
		     mands.  The default maximum level is 10000.

       watch deactivate	watchName
	      Deactivates the watch.  The -precmd and -postcmd procedures will
	      no longer	be invoked.

       watch info watchName
	      Returns  the configuration information associated	with the watch
	      watchName.  WatchName is the name	of a watch.

       watch names ?state?
	      Lists the	names of the watches for a given state.	 State may  be
	      one of the following: active, idle, or ignore.  If a state argu-
	      ment isn't specified,
	       all watches are listed.

KEYWORDS
       debug, profile

BLT				      2.5			      watch(n)

NAME | SYNOPSIS | DESCRIPTION | INTRODUCTION | EXAMPLE | OPERATIONS | KEYWORDS

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

home | help