New debugger-trap function to break to GDB

* src/eval.c: new primitive debugger-trap
* src/.gdbinit: set breakpoint to Fdebugger_trap
* etc/DEBUG: document it.
Remove suggestion to use Fredraw_display.

This do-nothing primitive gives control to GDB, and for debugging
convenience a breakpoint is set by default in .gdbinit.

2 files changed, 21 insertions, 0 deletions

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);
 }