Use SIGQUIT for DWARF backtraces instead of SIGUSR2

Reviewers: austin, erikd, simonmar

Subscribers: NicolasT, rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D3979

3 files changed, 21 insertions, 10 deletions

diff --git a/docs/users_guide/8.4.1-notes.rst b/docs/users_guide/8.4.1-notes.rst
index 9a1235f5a8..4f3ff263cb 100644
--- a/docs/users_guide/8.4.1-notes.rst
+++ b/docs/users_guide/8.4.1-notes.rst
@@ -157,6 +157,12 @@ Runtime system
 
 - The GHCi runtime linker on Windows now supports the `big-obj` file format.
 
+- The runtime system's :ref:`native stack backtrace <backtrace-signal>` support
+  on POSIX platforms is now triggered by ``SIGQUIT`` instead of ``SIGUSR2`` as
+  it was in previous releases. This change is to bring GHC's behavior into
+  compliance with the model set by the most Java virtual machine
+  implementations.
+
 Template Haskell
 ~~~~~~~~~~~~~~~~
 
diff --git a/docs/users_guide/debug-info.rst b/docs/users_guide/debug-info.rst
index 558da594a0..d1bd28c823 100644
--- a/docs/users_guide/debug-info.rst
+++ b/docs/users_guide/debug-info.rst
@@ -185,16 +185,21 @@ Stack trace functionality is exposed for use by Haskell programs in the
 :base-ref:`GHC.ExecutionStack.` module. See the Haddock
 documentation in this module for details regarding usage.
 
-Requesting a stack trace with ``SIGUSR2``
+.. _backtrace_signal:
+
+Requesting a stack trace with ``SIGQUIT``
 -----------------------------------------
 
 On POSIX-compatible platforms GHC's runtime system (when built with ``libdw``
-support) will produce a stack trace on ``stderr`` when a ``SIGUSR2`` signal is
-received. For instance (using the same ``fib.hs`` as above),
+support) will produce a stack trace on ``stderr`` when a ``SIGQUIT`` signal is
+received (on many systems this signal can be sent using :kbd:`Ctrl-\\`). For
+instance (using the same ``fib.hs`` as above),
 
 .. code-block:: sh
 
-    $ ./fib  &  killall -SIGUSR2 fib
+    $ ./fib  &  killall -SIGQUIT fib
+
+    Caught SIGQUIT; Backtrace:
     0x7f3176b15dd8    dwfl_thread_getframes (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
     0x7f3176b1582f    (null) (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
     0x7f3176b15b57    dwfl_getthreads (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
diff --git a/rts/posix/Signals.c b/rts/posix/Signals.c
index 6b728905e6..e75f99def8 100644
--- a/rts/posix/Signals.c
+++ b/rts/posix/Signals.c
@@ -528,10 +528,10 @@ shutdown_handler(int sig STG_UNUSED)
 }
 
 /* -----------------------------------------------------------------------------
- * SIGUSR2 handler.
+ * SIGQUIT handler.
  *
  * We try to give the user an indication of what we are currently doing
- * in response to SIGUSR2.
+ * in response to SIGQUIT.
  * -------------------------------------------------------------------------- */
 static void
 backtrace_handler(int sig STG_UNUSED)
@@ -539,7 +539,7 @@ backtrace_handler(int sig STG_UNUSED)
 #if USE_LIBDW
     LibdwSession *session = libdwInit();
     Backtrace *bt = libdwGetBacktrace(session);
-    fprintf(stderr, "\nCaught SIGUSR2; Backtrace:\n");
+    fprintf(stderr, "\nCaught SIGQUIT; Backtrace:\n");
     libdwPrintBacktrace(session, stderr, bt);
     backtraceFree(bt);
     libdwFree(session);
@@ -721,12 +721,12 @@ initDefaultHandlers(void)
         sysErrorBelch("warning: failed to install SIGPIPE handler");
     }
 
-    // Print a backtrace on SIGUSR2
+    // Print a backtrace on SIGQUIT
     action.sa_handler = backtrace_handler;
     sigemptyset(&action.sa_mask);
     action.sa_flags = 0;
-    if (sigaction(SIGUSR2, &action, &oact) != 0) {
-        sysErrorBelch("warning: failed to install SIGUSR2 handler");
+    if (sigaction(SIGQUIT, &action, &oact) != 0) {
+        sysErrorBelch("warning: failed to install SIGQUIT handler");
     }
 
     set_sigtstp_action(true);