BSD 4_3 development

[unix-history] / usr / lib / lisp / manual / ch11.r

                        CHAPTER  11


              The Joseph Lister Trace Package




     The Joseph Lister[] Trace package is an important  tool
for the interactive debugging of a Lisp program.  It  allows
you  to  examine selected  calls to a function or functions,
and optionally to stop execution  of  the  Lisp  program  to
examine the values of variables.

     The trace package is a set of Lisp programs located  in
the    Lisp   program   library   (usually   in   the   file
/usr/lib/lisp/trace.l).  Although not normally loaded in the
Lisp  system,  the  package will be loaded in when the first
call to _\bt_\br_\ba_\bc_\be is made.

(trace [ls_arg1 ...])

     WHERE:   the form of the ls_arg_\bi is described below.

     RETURNS: a list of the  function  sucessfully  modified
              for  tracing.   If  no  arguments are given to
              _\bt_\br_\ba_\bc_\be, a list of all functions currently being
              traced is returned.

     SIDE EFFECT: The function definitions of the  functions
                  to trace are modified.


The ls_arg_\bi can have one of the following forms:


  foo - when foo is entered and exited, the  trace  informa-
       tion will be printed.


  (foo break) - when foo is entered  and  exited  the  trace
       information  will  be  printed.  Also, just after the
       trace information for foo is printed upon entry,  you
       will  be put in  a special break loop.  The prompt is
       `T>' and you may type any Lisp  expression,  and  see
       its  value printed.  The _\bith argument to the function
       just called can be accessed as (arg _\bi).  To leave the
       trace   loop,  just  type  ^D  or  (tracereturn)  and
____________________
\e9   []_\bL_\bi_\bs_\bt_\be_\br, _\bJ_\bo_\bs_\be_\bp_\bh     1st  Baron  Lister  of  Lyme  Regis,
1827-1912; English surgeon: introduced antiseptic surgery.



\e9The Joseph Lister Trace Package                         11-1







The Joseph Lister Trace Package                         11-2


       execution will continue.  Note that ^D will work only
       on UNIX systems.


  (foo if expression) - when foo is entered and the  expres-
       sion evaluates to non-nil, then the trace information
       will be printed for both exit and entry.  If  expres-
       sion evaluates to nil, then no trace information will
       be printed.


  (foo ifnot expression) -  when  foo  is  entered  and  the
       expression  evaluates to nil, then the trace informa-
       tion will be printed for both  entry  and  exit.   If
       both  if and ifnot are specified, then the if expres-
       sion must evaluate to non nil AND the  ifnot  expres-
       sion  must  evaluate to nil for the trace information
       to be printed out.


  (foo evalin expression) - when foo is  entered  and  after
       the  entry  trace  information is printed, expression
       will be evaluated. Exit  trace  information  will  be
       printed when foo exits.


  (foo evalout expression) -  when  foo  is  entered,  entry
       trace  information  will be printed.  When foo exits,
       and before the exit  trace  information  is  printed,
       expression will be evaluated.


  (foo evalinout expression) - this has the same  effect  as
       (trace (foo evalin expression evalout expression)).


  (foo lprint) - this tells _\bt_\br_\ba_\bc_\be to use the  level  printer
       when  printing  the arguments to and the result of  a
       call to foo.  The level printer prints only  the  top
       levels  of  list structure. Any structure below three
       levels is printed as a &.  This allows you  to  trace
       functions with massive arguments or results.



          The following trace options  permit  one  to  have
     greater control over each action which takes place when
     a function is traced.  These options are only meant  to
     be used by people who need special hooks into the trace
     package.  Most people should skip reading this section.


  (foo traceenter  tefunc)  -  this  tells  _\bt_\br_\ba_\bc_\be  that  the


                                      Printed: July 27, 1983







The Joseph Lister Trace Package                         11-3


       function  to be called when foo is entered is tefunc.
       tefunc should be a lambda of two arguments, the first
       argument  will  be  bound to the name of the function
       being traced, foo in this case.  The second  argument
       will  be  bound to the list of arguments to which foo
       should be applied.  The function tefunc should  print
       some  sort  of "entering foo" message.  It should not
       apply foo to the arguments,  however.  That  is  done
       later on.


  (foo traceexit txfunc) - this tells _\bt_\br_\ba_\bc_\be that  the  func-
       tion  to  be  called  when  foo  is exited is txfunc.
       txfunc should be a lambda of two arguments, the first
       argument  will  be  bound to the name of the function
       being traced, foo in this case.  The second  argument
       will  be bound to the result of the call to foo.  The
       function txfunc should print some  sort  of  "exiting
       foo" message.


  (foo evfcn evfunc) - this tells _\bt_\br_\ba_\bc_\be that the form evfunc
       should  be  evaluated to get the value of foo applied
       to its arguments. This option is a bit different from
       the  other  special options since evfunc will usually
       be an expression, not just the name  of  a  function,
       and  that  expression will be specific to the evalua-
       tion of  function  foo.   The  argument  list  to  be
       applied will be available as T-arglist.


  (foo printargs prfunc) - this tells _\bt_\br_\ba_\bc_\be to  used  prfunc
       to print the arguments  to be applied to the function
       foo.  prfunc should be a lambda of one argument.  You
       might  want  to use this option if you wanted a print
       function which could  handle  circular  lists.   This
       option  will work only if you do not specify your own
       traceenter function.  Specifying the option lprint is
       just  a simple way of changing the printargs function
       to the level printer.


  (foo printres prfunc) - this tells _\bt_\br_\ba_\bc_\be to use prfunc  to
       print the result of evaluating foo.  prfunc should be
       a lambda of one argument.  This option will work only
       if  you  do  not specify your own traceexit function.
       Specifying the option lprint changes printres to  the
       level printer.



          You may specify more  than  one  option  for  each
     function traced. For example:


                                      Printed: July 27, 1983







The Joseph Lister Trace Package                         11-4


     (_\bt_\br_\ba_\bc_\be (_\bf_\bo_\bo _\bi_\bf (_\be_\bq _\b3 (_\ba_\br_\bg _\b1)) _\bb_\br_\be_\ba_\bk _\bl_\bp_\br_\bi_\bn_\bt) (_\bb_\ba_\br _\be_\bv_\ba_\bl_\bi_\bn
     (_\bp_\br_\bi_\bn_\bt _\bx_\by_\bz_\bz_\by)))

     This tells _\bt_\br_\ba_\bc_\be to trace two more functions,  foo  and
     bar.   Should  foo be called with the first argument _\be_\bq
     to 3, then the entering foo  message  will  be  printed
     with  the  level  printer.   Next it will enter a trace
     break loop, allowing you to evaluate any  lisp  expres-
     sions.  When you exit the trace break loop, foo will be
     applied to its arguments and the resulting  value  will
     be printed, again using the level printer.  Bar is also
     traced, and each time bar is entered, an  entering  bar
     message  will  be  printed  and then the value of xyzzy
     will be printed.  Next bar will be applied to its argu-
     ments  and  the  result  will  be printed.  If you tell
     _\bt_\br_\ba_\bc_\be to trace a function which is already  traced,  it
     will  first  _\bu_\bn_\bt_\br_\ba_\bc_\be  it.   Thus if you want to specify
     more than one trace option for a function, you must  do
     it all at once.  The following is _\bn_\bo_\bt equivalent to the
     preceding call to _\bt_\br_\ba_\bc_\be for foo:

     (_\bt_\br_\ba_\bc_\be (_\bf_\bo_\bo  _\bi_\bf  (_\be_\bq  _\b3  (_\ba_\br_\bg  _\b1)))  (_\bf_\bo_\bo  _\bb_\br_\be_\ba_\bk)  (_\bf_\bo_\bo
     _\bl_\bp_\br_\bi_\bn_\bt))

     In this example, only the last option, lprint, will  be
     in effect.

          If the symbol $tracemute is given a non nil value,
     printing  of  the  function name and arguments on entry
     and exit will be surpressed.  This is particularly use-
     ful  if  the  function you are tracing fails after many
     calls to it.  In this case  you  would  tell  _\bt_\br_\ba_\bc_\be  to
     trace  the function, set $tracemute to t, and begin the
     computation.  When an error occurs  you  can  use  _\bt_\br_\ba_\b-
     _\bc_\be_\bd_\bu_\bm_\bp to print out the current trace frames.

          Generally the trace package has its  own  internal
     names  for  the the lisp functions it uses, so that you
     can feel free to trace system functions like  _\bc_\bo_\bn_\bd  and
     not worry about adverse interaction with the actions of
     the trace package.  You can trace any type of function:
     lambda,  nlambda,  lexpr  or  macro whether compiled or
     interpreted and you can  even  trace  array  references
     (however  you  should  not attempt to store in an array
     which has been traced).

          When tracing compiled code keep in mind that  many
     function  calls  are  translated  directly  to  machine
     language  or other equivalent  function calls.  A  full
     list of open coded functions is listed at the beginning
     of  the  liszt  compiler  source.   _\bT_\br_\ba_\bc_\be  will  do   a
     (_\bs_\bs_\bt_\ba_\bt_\bu_\bs _\bt_\br_\ba_\bn_\bs_\bl_\bi_\bn_\bk _\bn_\bi_\bl)  to  insure that the new traced
     definitions it defines are called instead  of  the  old


                                      Printed: July 27, 1983







The Joseph Lister Trace Package                         11-5


     untraced  ones.  You may notice that compiled code will
     run slower after this is done.

(traceargs s_func [x_level])

     WHERE:   if x_level is missing it is assumed to be 1.

     RETURNS: the arguments to the x_level_\bt_\bh call to  traced
              function s_func are returned.

(tracedump)

     SIDE EFFECT: the  currently  active  trace  frames  are
                  printed  on  the terminal.  returns a list
                  of functions untraced.

(untrace [s_arg1 ...])

     RETURNS: a list of the functions which were untraced.

     NOTE: if no arguments  are  given,  all  functions  are
           untraced.

     SIDE EFFECT: the old function definitions of all traced
                  functions  are restored except in the case
                  where it appears that the current  defini-
                  tion  of  a  function  was  not created by
                  trace.
























\e9

\e9                                      Printed: July 27, 1983