22.1.6 Debugger Commands

Inside the debugger (in Debugger mode), these special commands are available in addition to the usual cursor motion commands. (Keep in mind that all the usual facilities of XEmacs, such as switching windows or buffers, are still available.)

The most important use of debugger commands is for stepping through code, so that you can see how control flows. The debugger can step through the control structures of an interpreted function, but cannot do so in a byte-compiled function. If you would like to step through a byte-compiled function, replace it with an interpreted definition of the same function. (To do this, visit the source file for the function and type C-M-x on its definition.)

Here is a list of Debugger mode commands:

c

Exit the debugger and continue execution. This resumes execution of the program as if the debugger had never been entered (aside from the effect of any variables or data structures you may have changed while inside the debugger).

Continuing when an error or quit was signalled will cause the normal action of the signalling to take place. If you do not want this to happen, but instead want the program execution to continue as if the call to signal did not occur, use the r command.

d

Continue execution, but enter the debugger the next time any Lisp function is called. This allows you to step through the subexpressions of an expression, seeing what values the subexpressions compute, and what else they do.

The stack frame made for the function call which enters the debugger in this way will be flagged automatically so that the debugger will be called again when the frame is exited. You can use the u command to cancel this flag.

b

Flag the current frame so that the debugger will be entered when the frame is exited. Frames flagged in this way are marked with stars in the backtrace buffer.

u

Don’t enter the debugger when the current frame is exited. This cancels a b command on that frame.

e

Read a Lisp expression in the minibuffer, evaluate it, and print the value in the echo area. The debugger alters certain important variables, and the current buffer, as part of its operation; e temporarily restores their outside-the-debugger values so you can examine them. This makes the debugger more transparent. By contrast, M-: does nothing special in the debugger; it shows you the variable values within the debugger.

q

Terminate the program being debugged; return to top-level XEmacs command execution.

If the debugger was entered due to a C-g but you really want to quit, and not debug, use the q command.

r

Return a value from the debugger. The value is computed by reading an expression with the minibuffer and evaluating it.

The r command is useful when the debugger was invoked due to exit from a Lisp call frame (as requested with b); then the value specified in the r command is used as the value of that frame. It is also useful if you call debug and use its return value.

If the debugger was entered at the beginning of a function call, r has the same effect as c, and the specified return value does not matter.

If the debugger was entered through a call to signal (i.e. as a result of an error or quit), then returning a value will cause the call to signal itself to return, rather than throwing to top-level or invoking a handler, as is normal. This allows you to correct an error (e.g. the type of an argument was wrong) or continue from a debug-on-quit as if it never happened.

Note: Some errors (e.g. any error signalled using the error function, and many errors signalled from a primitive function) are not continuable. If you return a value from them and continue execution, then the error will immediately be signalled again. Other errors (e.g. wrong-type-argument errors) will be continually resignalled until the problem is corrected.