Internals of the Debugger
-------------------------

   This section describes functions and variables used internally by the
debugger.

 - 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 &optional stream detailed
     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'.

     The backtrace is normally printed to `standard-output', but this
     can be changed by specifying a value for STREAM.  If DETAILED is
     non-`nil', the backtrace also shows places where currently active
     variable bindings, catches, condition-cases, and unwind-protects
     were made as well as function calls.

     In the following example, a Lisp expression calls `backtrace'
     explicitly.  This prints the backtrace to the stream
     `standard-output': in this case, to the buffer `backtrace-output'.
     Each line of the backtrace represents one function call.  The
     line shows the values of the function's arguments if they are all
     known.  If they are still being computed, the line says so.  The
     arguments of special forms are elided.

          (with-output-to-temp-buffer "backtrace-output"
            (let ((var 1))
              (save-excursion
                (setq var (eval '(progn
                                   (1+ var)
                                   (list 'testing (backtrace))))))))
          
               => nil
          
          ----------- Buffer: backtrace-output ------------
            backtrace()
            (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 ...")
            eval-print-last-sexp(nil)
          * call-interactively(eval-print-last-sexp)
          ----------- Buffer: backtrace-output ------------

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

 - Variable: debug-on-next-call
     If this variable is non-`nil', it says to call the debugger before
     the next `eval', `apply' or `funcall'.  Entering the debugger sets
     `debug-on-next-call' to `nil'.

     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 stack frame LEVEL
     levels down the stack, giving it the value FLAG.  If FLAG is
     non-`nil', this will cause the debugger to be entered when that
     frame later exits.  Even a nonlocal exit through that frame will
     enter the debugger.

     This function is used only by the debugger.

 - Variable: command-debug-status
     This variable records the debugging status of the 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 command.

     The advantage, for the debugger, of using this variable rather than
     another global variable is that the data will never carry over to a
     subsequent 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 stack frame FRAME-NUMBER 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 the CAR
     of the 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 FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'.