elisp: Internals of Debugger
17.1.8 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. This function should
invoke 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’ (
Invoking the Debugger).
-- 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, a Lisp expression calls ‘backtrace’
explicitly. This prints the backtrace to the stream
‘standard-output’, which, in this case, is 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))))))))
⇒ (testing 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((with-output-to-temp-buffer ...))
eval-last-sexp-1(nil)
eval-last-sexp(nil)
call-interactively(eval-last-sexp)
----------- Buffer: backtrace-output ------------
-- 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 invocation.
The advantage of using this variable rather than an ordinary global
variable is that the data will never carry over to a subsequent
command invocation.
This variable is obsolete and will be removed in future versions.
-- 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 return 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’.
Info Catalog
elisp: Invoking the Debugger
elisp: Debugger