diff --git a/etc/DEBUG b/etc/DEBUG index 25049ad42b4..44f19900c64 100644 --- a/etc/DEBUG +++ b/etc/DEBUG @@ -211,16 +211,17 @@ the debugger, but before running it, is the most efficient way of making sure control will be returned to the debugger when you need that. +There is a default function to give control to the debugger. It is +called debugger-trap. This is a do-nothing primitive, as a convenient +point to return control to the debugger. You can invoke interactively +with "M-x debugger-trap RET". The src/.gdbinit file in the Emacs source +distribution sets a breakpoint on this function. + 'Fsignal' is a very useful place to put a breakpoint in. All Lisp errors go through there. If you are only interested in errors that would fire the Lisp debugger, breaking at 'maybe_call_debugger' is useful. -Another technique for getting control to the debugger is to put a -breakpoint in some rarely used function. One such convenient function -is Fredraw_display, which you can invoke at will interactively with -"M-x redraw-display RET". - It is also useful to have a guaranteed way to return to the debugger at any arbitrary time. When using X, this is easy: type C-z at the window where you are interacting with GDB, and it will stop Emacs just diff --git a/src/.gdbinit b/src/.gdbinit index d3bfad59486..0eab7ac9afa 100644 --- a/src/.gdbinit +++ b/src/.gdbinit @@ -1314,6 +1314,11 @@ if defined_WINDOWSNT end end +# Break at default trap function to give control to GDB. +# Call from Emacs with M-x debugger-trap +break Fdebugger_trap + + # Put the Python code at the end of .gdbinit so that if GDB does not # support Python, GDB will do all the above initializations before # reporting an error. diff --git a/src/eval.c b/src/eval.c index 204adb62472..829d6104618 100644 --- a/src/eval.c +++ b/src/eval.c @@ -3091,6 +3091,21 @@ FUNCTIONP (Lisp_Object object) return false; } +DEFUN ("debugger-trap", Fdebugger_trap, Sdebugger_trap, 0, 0, "", + doc: /* Trap execution flow and hand over control to GDB. +The Emacs source file src/.gdbinit uses this via the GDB command +"break Fdebugger_trap". + +This function has no effect. It is reserved for debugging, and is not +called by Emacs otherwise. + +For Lisp debugging see debug, as well as edebug, in the manual: +"(elisp) Debugging". */) + (void) +{ + return Qnil; +} + Lisp_Object funcall_general (Lisp_Object fun, ptrdiff_t numargs, Lisp_Object *args) { @@ -4617,4 +4632,5 @@ alist of active lexical bindings. */); defsubr (&Sspecial_variable_p); DEFSYM (Qfunctionp, "functionp"); defsubr (&Sfunctionp); + defsubr (&Sdebugger_trap); }