Subject: bug#75632: 31.0.50; igc: Crash report

From: Pip Cet <[email-masked]>
Date: Sat, 25 Jan 2025 09:31:05 +0000

"Richard Stallman" <[email-masked]> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > I guess I was confused and thought that both SIGUSR1 and SIGUSR2 were
>   > supposed to start the debugger.
>
> Could people make sure that the documentation is up to date about this
> point in all the places it is described?

It currently isn't; the section on sigusr1/sigusr2 in commands.texi
doesn't mention debug-on-event, and the section on debug-on-event in
debugging.texi doesn't mention its default value.

That means anyone attempting to bind sigusr2 as a key will be in for a
big surprise, because the curent behavior is to enter the debugger by
default.

This diff may explain better than a long list what I'd like to change
about the documentation, even if the wording is bad.

It is very rare to need to alter or call (after the patch) the
debug-on-error variable/function.  Setting it to nil may be useful in
exceptional situations, but I don't actually see the need for using
SIGUSR1 at this time.  My impression was that this was originally meant
to be expanded to more signals (that would be useful, as some other
programs generate specific events and it's hard to modify them), but
that never happened.

Even if the sentence about signals not carrying additional information
were accurate (on GNU/Linux, it simply isn't), I don't see the relevance
to this section at all, so I removed it.

Again, the wording can and should be improved, but the old docs are
inaccurate and the new ones, I hope, less so.

Pip

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 39514145a1e..9ccc07a3291 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2731,16 +2731,20 @@ Misc Events
 @cindex user signals
 @item sigusr1
 @itemx sigusr2
-These events are generated when the Emacs process receives
-the signals @code{SIGUSR1} and @code{SIGUSR2}.  They contain no
-additional data because signals do not carry additional information.
-They can be useful for debugging (@pxref{Error Debugging}).
-
-To catch a user signal, bind the corresponding event to an interactive
-command in the @code{special-event-map} (@pxref{Controlling Active Maps}).
-The command is called with no arguments, and the specific signal event is
-available in @code{last-input-event} (@pxref{Event Input Misc}.  For
-example:
+When the Emacs process receives @code{SIGUSR1}, the @code{sigusr1} event
+is generated and treated as an input event.  This event contains no
+additional data.  This can be useful for debugging (@pxref{Error
+Debugging}).
+
+It is possible to modify @code{debug-on-event} to do the same when
+@code{SIGUSR2} is received instead, or for both events.  By default,
+binding @code{sigusr2} has no effect.
+
+To catch a user signal which is not used by @code{debug-on-event}, bind
+the corresponding event to an interactive command in the
+@code{special-event-map} (@pxref{Controlling Active Maps}).  The command
+is called with no arguments, and the specific signal event is available
+in @code{last-input-event} (@pxref{Event Input Misc}.  For example:
 
 @smallexample
 (defun sigusr-handler ()
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 9b36f9ecdb2..d9b12137b4b 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -112,6 +112,14 @@ Error Debugging
 defined in this subsection to debug errors in Lisp that the redisplay
 code has invoked.  @xref{Debugging Redisplay}, for help with these.
 
+One way to invoke the debugger even in extreme situations is to send
+Emacs a @code{SIGUSR2} signal.  This will make Emacs try to enter the
+debugger as soon as possible after the signal.  There is a small risk
+this results in unexpected or erroneous behavior.
+
+In this case, @code{special-event-map} or other bindings are not
+consulted.
+
 @defopt debug-on-error
 This variable determines whether the debugger is called when an error
 is signaled and not handled.  If @code{debug-on-error} is @code{t},
@@ -187,12 +195,13 @@ Error Debugging
 @end defopt
 
 @defopt debug-on-event
-If you set @code{debug-on-event} to a special event (@pxref{Special
-Events}), Emacs will try to enter the debugger as soon as it receives
-this event, bypassing @code{special-event-map}.  At present, the only
-supported values correspond to the signals @code{SIGUSR1} and
-@code{SIGUSR2} (this is the default).  This can be helpful when
-@code{inhibit-quit} is set and Emacs is not otherwise responding.
+You can change which signals enter the debugger by setting
+@code{debug-on-event} to an event name; the default is @code{sigusr2}.
+This can be helpful when @code{inhibit-quit} is set and
+Emacs is not otherwise responding.
+
+At present, the only other supported values are @code{sigusr1}, to use
+@code{SIGUSR1} instead, and @code{nil}, disabling the feature entirely.
 @end defopt
 
 @cindex message, finding what causes a particular message