(lispref.info)Invoking the Debugger


Next: Internals of Debugger Prev: Debugger Commands Up: Debugger

Invoking the Debugger
---------------------

   Here we describe fully the function used to invoke the debugger.

 - Function: debug &rest DEBUGGER-ARGS
     This function enters the debugger.  It switches buffers to a buffer
     named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
     recursive entry to the debugger, etc.), and fills it with
     information about the stack of Lisp function calls.  It then
     enters a recursive edit, leaving that buffer in Debugger mode and
     displayed in the selected window.

     Debugger mode provides a `c' command which operates by exiting the
     recursive edit, switching back to the previous buffer, and
     returning to whatever called `debug'.  The `r' command also
     returns from `debug'.  These are the only ways the function
     `debug' can return to its caller.

     If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
     if it is not one of the following special values), then the rest
     of the arguments to `debug' are printed at the top of the
     `*Backtrace*' buffer.  This mechanism is used to display a message
     to the user.

     However, if the first argument passed to `debug' is one of the
     following special values, then it has special significance.
     Normally, these values are passed to `debug' only by the internals
     of Emacs and the debugger, and not by programmers calling `debug'.

     The special values are:

    `lambda'
          When the first argument is `lambda', the debugger displays
          `Entering:' as a line of text at the top of the buffer.  This
          means that a function is being entered when
          `debug-on-next-call' is non-`nil'.

    `debug'
          When the first argument is `debug', the debugger displays
          `Entering:' just as in the `lambda' case.  However, `debug'
          as the argument indicates that the reason for entering the
          debugger is that a function set to debug on entry is being
          entered.

          In addition, `debug' as the first argument directs the
          debugger to mark the function that called `debug' so that it
          will invoke the debugger when exited.  (When `lambda' is the
          first argument, the debugger does not do this, because it has
          already been done by the interpreter.)

    `t'
          When the first argument is `t', the debugger displays the
          following as the top line in the buffer:

               Beginning evaluation of function call form:

          This indicates that it was entered due to the evaluation of a
          list form at a time when `debug-on-next-call' is non-`nil'.

    `exit'
          When the first argument is `exit', it indicates the exit of a
          stack frame previously marked to invoke the debugger on exit.
          The second argument given to `debug' in this case is the
          value being returned from the frame.  The debugger displays
          `Return value:' on the top line of the buffer, followed by
          the value being returned.

    `error'
          When the first argument is `error', the debugger indicates
          that it is being entered because an error or `quit' was
          signaled and not handled, by displaying `Signaling:' followed
          by the error signaled and any arguments to `signal'.  For
          example,

               (let ((debug-on-error t))
                    (/ 1 0))
               
               ------ Buffer: *Backtrace* ------
               Signaling: (arith-error)
                 /(1 0)
               ...
               ------ Buffer: *Backtrace* ------

          If an error was signaled, presumably the variable
          `debug-on-error' is non-`nil'.  If `quit' was signaled, then
          presumably the variable `debug-on-quit' is non-`nil'.

    `nil'
          Use `nil' as the first of the DEBUGGER-ARGS when you want to
          enter the debugger explicitly.  The rest of the DEBUGGER-ARGS
          are printed on the top line of the buffer.  You can use this
          feature to display messages--for example, to remind yourself
          of the conditions under which `debug' is called.


automatically generated by info2www