(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:
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'.
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
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.)
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'.
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.
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
(let ((debug-on-error t))
(/ 1 0))
------ Buffer: *Backtrace* ------
------ 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'.
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