22.1.7 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, showing the backtrace buffer in Debugger mode.

The Debugger mode c and r commands exit the recursive edit; then debug switches back to the previous buffer and returns to whatever called debug. This is the only way 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 special values in the table below), then debug displays the rest of its arguments 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 XEmacs and the debugger, and not by programmers calling debug.

The special values are:

lambda

A first argument of lambda means debug was called because of entry to a function when debug-on-next-call was non-nil. The debugger displays ‘Entering:’ as a line of text at the top of the buffer.

debug

debug as first argument indicates a call to debug because of entry to a function that was set to debug on entry. The debugger displays ‘Entering:’, just as in the lambda case. It also marks the stack frame for that function so that it will invoke the debugger when exited.

t

When the first argument is t, this indicates a call to debug due to evaluation of a list form when debug-on-next-call is non-nil. The debugger displays the following as the top line in the buffer:

Beginning evaluation of function call form:

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.