Seth Woolley's Man Viewer

Manual for trace - man n trace

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

trace(3x,n,3x _nc_tracebits)(n)                     Tcl Built-In Commands                    trace(3x,n,3x _nc_tracebits)(n)



NAME
       trace(3x,n,3x _nc_tracebits)  -  Monitor  variable accesses, command usages and command execu-
       tions

SYNOPSIS
       trace(3x,n,3x _nc_tracebits) 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(3x,n,3x _nc_tracebits) add type name ops ?args?
              Where type is command, execution, or variable.

              trace(3x,n,3x _nc_tracebits) add command name ops command
                     Arrange  for command to be executed whenever command name
                     is modified in(1,8) 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(8,n) will be thrown.

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

                     rename(1,2,n) Invoke command whenever the  command  is  renamed.
                            Note  that renaming to the empty string(3,n) is consid-
                            ered  deletion,  and  will  not  be  traced   with
                            'rename(1,2,n)'.

                     delete Invoke  command when the command is deleted.  Com-
                            mands can  be  deleted  explicitly  by  using  the
                            rename(1,2,n)  command  to rename(1,2,n) 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(1,8) which  to  exe-
                            cute them.

                     When  the  trace(3x,n,3x _nc_tracebits)  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(3,n) if(3,n)  this  is  a  'delete'
                     operation).   Op  indicates  what operation is being per-
                     formed on the command, and is one of rename(1,2,n) or delete  as
                     defined  above.   The  trace(3x,n,3x _nc_tracebits)  operation cannot be used to
                     stop a command  from  being  deleted.   Tcl  will  always
                     remove the command once the trace(3x,n,3x _nc_tracebits) is complete.  Recursive
                     renaming or deleting will not cause further traces of the
                     same type to be evaluated, so a delete trace(3x,n,3x _nc_tracebits) which itself
                     deletes the command,  or  a  rename(1,2,n)  trace(3x,n,3x _nc_tracebits)  which  itself
                     renames  the command will not cause further trace(3x,n,3x _nc_tracebits) evalua-
                     tions to occur.  Both oldName and newName are fully qual-
                     ified with any namespace(s) in(1,8) which they appear.

              trace(3x,n,3x _nc_tracebits) 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(8,n) 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(3,n)  we
                            have 'proc(5,n) foo {} { puts(3,n) "hello" }', then a enter-
                            step trace(3x,n,3x _nc_tracebits)  would  be  invoked  just  before  puts(3,n)
                            "hello" is executed.  Setting a enterstep trace(3x,n,3x _nc_tracebits) on
                            a command will not result in(1,8) an error(8,n) and is  sim-
                            ply 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(3x,n,3x _nc_tracebits) on a command will not result in(1,8) an error(8,n) and
                            is simply ignored.

                     When  the  trace(3x,n,3x _nc_tracebits)  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(3,n) op Command-string gives the complete current  com-
                     mand being executed (the traced command for a enter oper-
                     ation, an arbitrary command for a  enterstep  operation),
                     including all arguments in(1,8) their fully expanded form.  Op
                     indicates what operation is being performed on  the  com-
                     mand  execution,  and  is  one  of  enter or enterstep as
                     defined above.  The trace(3x,n,3x _nc_tracebits) operation can be used  to  stop
                     the  command  from  executing, by deleting the command in(1,8)
                     question.  Of course when  the  command  is  subsequently
                     executed, an 'invalid command' error(8,n) will occur.

                     For  leave  and  leavestep  operations:  command command-
                     string(3,n) 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(1,8)  their  fully
                     expanded form.  Code gives the result code of that execu-
                     tion,  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 unintuitive results, since the invoked com-
                     mands from one trace(3x,n,3x _nc_tracebits) can themselves lead to further  com-
                     mand invocations for other traces.

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

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

                     When multiple traces are set(7,n,1 builtins) on name, then for enter  and
                     enterstep  operations, the traced commands are invoked in(1,8)
                     the reverse order of how the traces were originally  cre-
                     ated;  and for leave and leavestep operations, the traced
                     commands are invoked in(1,8) the original order of creation.

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

              trace(3x,n,3x _nc_tracebits) add variable name ops command
                     Arrange for command to be executed whenever variable name
                     is accessed in(1,8) 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(1,5,n) 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(1,2,n) that the
                            array command is invoked.  If  name  is  a  scalar
                            variable,  the  access(2,5)  via the array command will
                            not trigger the trace.

                     read(2,n,1 builtins)   Invoke command whenever the variable is read.

                     write(1,2)  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(1,8) which to execute them.

                     When the trace(3x,n,3x _nc_tracebits) 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(3,n)  the variable is a scalar
                     then name1 gives the variable's  name  and  name2  is  an
                     empty  string(3,n);  if(3,n)  the variable is an array element then
                     name1 gives the name of the array  and  name2  gives  the
                     index into the array; if(3,n) an entire array is being deleted
                     and the trace(3x,n,3x _nc_tracebits) was registered 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(1,8) the trace(3x,n,3x _nc_tracebits) vari-
                     able command:  the upvar command allows  a  procedure  to
                     reference  a  variable  under a different name.  Op indi-
                     cates what operation is being performed on the  variable,
                     and is one of read(2,n,1 builtins), write(1,2), or unset as defined above.

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

                     For read(2,n,1 builtins) and write(1,2) 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(2,n,1 builtins) or
                     write(1,2)  trace(3x,n,3x _nc_tracebits),  then the new value will be returned as the
                     result of the traced operation.  The  return  value  from
                     command  is ignored except that if(3,n) it returns an error(8,n) of
                     any sort(1,3) then the traced operation also returns an  error(8,n)
                     with the same error(8,n) message returned by the trace(3x,n,3x _nc_tracebits) command
                     (this mechanism can be used to implement read-only  vari-
                     ables,  for  example).   For  write(1,2)  traces,  command  is
                     invoked after the variable's value has been  changed;  it
                     can  write(1,2)  a new value into the variable to override the
                     original value specified  in(1,8)  the  write(1,2)  operation.   To
                     implement  read-only  variables,  command  will  have  to
                     restore the old value of the variable.

                     While command is executing during a read(2,n,1 builtins) or write(1,2)  trace(3x,n,3x _nc_tracebits),
                     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(3,n)  command  unsets  the  variable  then
                     unset traces will be invoked.

                     When  an unset trace(3x,n,3x _nc_tracebits) 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(3x,n,3x _nc_tracebits) will be invoked  in(1,8)  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(3,n) an
                     unset trace(3x,n,3x _nc_tracebits) command creates a new trace(3x,n,3x _nc_tracebits) and accesses  the
                     variable, the trace(3x,n,3x _nc_tracebits) will be invoked.  Any errors in(1,8) unset
                     traces are ignored.

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

                     Once created, the trace(3x,n,3x _nc_tracebits) remains in(1,8)  effect  either  until
                     the  trace(3x,n,3x _nc_tracebits) is removed with the trace(3x,n,3x _nc_tracebits) 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(3x,n,3x _nc_tracebits) remove type name opList command
              Where type is either command, execution or variable.

              trace(3x,n,3x _nc_tracebits) remove command name opList command
                     If  there  is a trace(3x,n,3x _nc_tracebits) set(7,n,1 builtins) on command name with the opera-
                     tions and command given by opList and command,  then  the
                     trace(3x,n,3x _nc_tracebits)  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(3x,n,3x _nc_tracebits) remove execution name opList command
                     If  there  is a trace(3x,n,3x _nc_tracebits) set(7,n,1 builtins) on command name with the opera-
                     tions and command given by opList and command,  then  the
                     trace(3x,n,3x _nc_tracebits)  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(3x,n,3x _nc_tracebits) remove variable name opList command
                     If  there is a trace(3x,n,3x _nc_tracebits) set(7,n,1 builtins) on variable name with the opera-
                     tions and command given by opList and command,  then  the
                     trace(3x,n,3x _nc_tracebits)  is  removed,  so  that command will never again be
                     invoked.  Returns an empty string.

       trace(3x,n,3x _nc_tracebits) info(1,5,n) type name
              Where type is either command, execution or variable.

              trace(3x,n,3x _nc_tracebits) info(1,5,n) command name
                     Returns a list containing one element for each trace(3x,n,3x _nc_tracebits) cur-
                     rently  set(7,n,1 builtins)  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(7,n,1 builtins), then the result of the  com-
                     mand will be an empty string.  If name doesn't exist, the
                     command will throw an error.

              trace(3x,n,3x _nc_tracebits) info(1,5,n) execution name
                     Returns a list containing one element for each trace(3x,n,3x _nc_tracebits) cur-
                     rently  set(7,n,1 builtins)  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(7,n,1 builtins), then the result of the  com-
                     mand will be an empty string.  If name doesn't exist, the
                     command will throw an error.

              trace(3x,n,3x _nc_tracebits) info(1,5,n) variable name
                     Returns a list containing one element for each trace(3x,n,3x _nc_tracebits) cur-
                     rently set(7,n,1 builtins) 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(7,n,1 builtins),  then  the
                     result of the command will be an empty string.

       For backwards compatibility, three other subcommands are available:

              trace(3x,n,3x _nc_tracebits) variable name ops command
                     This  is  equivalent  to trace(3x,n,3x _nc_tracebits) add variable name ops com-
                     mand.

              trace(3x,n,3x _nc_tracebits) vdelete name ops command
                     This is equivalent to trace(3x,n,3x _nc_tracebits) remove variable name ops com-
                     mand

              trace(3x,n,3x _nc_tracebits) vinfo name
                     This is equivalent to trace(3x,n,3x _nc_tracebits) info(1,5,n) variable name

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


SEE ALSO
       set(7,n,1 builtins)(n), unset(n)


KEYWORDS
       read(2,n,1 builtins), command, rename(1,2,n), variable, write(1,2), trace(3x,n,3x _nc_tracebits), unset



Tcl                                   8.4                             trace(3x,n,3x _nc_tracebits)(n)

References for this manual (incoming links)