(lispref.info)Internals of Debugger

Prev: Invoking the Debugger Up: Debugger

Internals of the Debugger

   This section describes functions and variables used internally by the

 - Variable: debugger
     The value of this variable is the function to call to invoke the
     debugger.  Its value must be a function of any number of arguments
     (or, more typically, the name of a function).  Presumably this
     function will enter some kind of debugger.  The default value of
     the variable is `debug'.

     The first argument that Lisp hands to the function indicates why it
     was called.  The convention for arguments is detailed in the
     description of `debug'.

 - Command: backtrace
     This function prints a trace of Lisp function calls currently
     active.  This is the function used by `debug' to fill up the
     `*Backtrace*' buffer.  It is written in C, since it must have
     access to the stack to determine which function calls are active.
     The return value is always `nil'.

     In the following example, `backtrace' is called explicitly in a
     Lisp expression.  When the expression is evaluated, the backtrace
     is printed to the stream `standard-output': in this case, to the
     buffer `backtrace-output'.  Each line of the backtrace represents
     one function call.  If the arguments of the function call are all
     known, they are displayed; if they are being computed, that fact
     is stated.  The arguments of special forms are elided.

          (with-output-to-temp-buffer "backtrace-output"
            (let ((var 1))
                (setq var (eval '(progn
                                   (1+ var)
                                   (list 'testing (backtrace))))))))
               => nil

          ----------- Buffer: backtrace-output ------------
            (list ...computing arguments...)
            (progn ...)
            eval((progn (1+ var) (list (quote testing) (backtrace))))
            (setq ...)
            (save-excursion ...)
            (let ...)
            (with-output-to-temp-buffer ...)
            eval-region(1973 2142 #<buffer *scratch*>)
            byte-code("...  for eval-print-last-sexp ...")
          * call-interactively(eval-print-last-sexp)
          ----------- Buffer: backtrace-output ------------

     The character `*' indicates a frame whose debug-on-exit flag is

 - Variable: debug-on-next-call
     This variable determines whether the debugger is called before the
     next `eval', `apply' or `funcall'.  It is automatically reset to
     `nil' when the debugger is entered.

     The `d' command in the debugger works by setting this variable.

 - Function: backtrace-debug LEVEL FLAG
     This function sets the debug-on-exit flag of the eval frame LEVEL
     levels down to FLAG.  If FLAG is non-`nil', this will cause the
     debugger to be entered when that frame exits.  Even a nonlocal
     exit through that frame will enter the debugger.

     The debug-on-exit flag is an entry in the stack frame of a
     function call.  This flag is examined on every exit from a

     Normally, this function is only called by the debugger.

 - Variable: command-debug-status
     This variable records the debugging status of current interactive
     command.  Each time a command is called interactively, this
     variable is bound to `nil'.  The debugger can set this variable to
     leave information for future debugger invocations during the same

     The advantage of using this variable rather that defining another
     global variable is that the data will never carry over to a later
     other command invocation.

 - Function: backtrace-frame FRAME-NUMBER
     The function `backtrace-frame' is intended for use in Lisp
     debuggers.  It returns information about what computation is
     happening in the eval frame LEVEL levels down.

     If that frame has not evaluated the arguments yet (or is a special
     form), the value is `(nil FUNCTION ARG-FORMS...)'.

     If that frame has evaluated its arguments and called its function
     already, the value is `(t FUNCTION ARG-VALUES...)'.

     In the return value, FUNCTION is whatever was supplied as CAR of
     evaluated list, or a `lambda' expression in the case of a macro
     call.  If the function has a `&rest' argument, that is represented
     as the tail of the list ARG-VALUES.

     If the argument is out of range, `backtrace-frame' returns `nil'.

automatically generated by info2www