gh-127604: Add C stack dumps to faulthandler (#128159)

Author: ZeroIntensity

Doc/library/faulthandler.rst

@@ -66,10 +66,41 @@ Dumping the traceback
       Added support for passing file descriptor to this function.
 
 
+Dumping the C stack
+-------------------
+
+.. versionadded:: next
+
+.. function:: dump_c_stack(file=sys.stderr)
+
+   Dump the C stack trace of the current thread into *file*.
+
+   If the Python build does not support it or the operating system
+   does not provide a stack trace, then this prints an error in place
+   of a dumped C stack.
+
+.. _c-stack-compatibility:
+
+C Stack Compatibility
+*********************
+
+If the system does not support the C-level :manpage:`backtrace(3)`,
+:manpage:`backtrace_symbols(3)`, or :manpage:`dladdr(3)`, then C stack dumps
+will not work. An error will be printed instead of the stack.
+
+Additionally, some compilers do not support :term:`CPython's <CPython>`
+implementation of C stack dumps. As a result, a different error may be printed
+instead of the stack, even if the the operating system supports dumping stacks.
+
+.. note::
+
+   Dumping C stacks can be arbitrarily slow, depending on the DWARF level
+   of the binaries in the call stack.
+
 Fault handler state
 -------------------
 
-.. function:: enable(file=sys.stderr, all_threads=True)
+.. function:: enable(file=sys.stderr, all_threads=True, c_stack=True)
 
    Enable the fault handler: install handlers for the :const:`~signal.SIGSEGV`,
    :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`
@@ -81,6 +112,10 @@ Fault handler state
    The *file* must be kept open until the fault handler is disabled: see
    :ref:`issue with file descriptors <faulthandler-fd>`.
 
+   If *c_stack* is ``True``, then the C stack trace is printed after the Python
+   traceback, unless the system does not support it. See :func:`dump_c_stack` for
+   more information on compatibility.
+
    .. versionchanged:: 3.5
       Added support for passing file descriptor to this function.
 
@@ -95,6 +130,9 @@ Fault handler state
       Only the current thread is dumped if the :term:`GIL` is disabled to
       prevent the risk of data races.
 
+   .. versionchanged:: next
+      The dump now displays the C stack trace if *c_stack* is true.
+
 .. function:: disable()
 
    Disable the fault handler: uninstall the signal handlers installed by

Doc/whatsnew/3.14.rst

@@ -699,6 +699,15 @@ errno
   (Contributed by James Roy in :gh:`126585`.)
 
 
+faulthandler
+------------
+
+* Add support for printing the C stack trace on systems that
+  :ref:`support it <c-stack-compatibility>` via :func:`faulthandler.dump_c_stack`
+  or via the *c_stack* argument in :func:`faulthandler.enable`.
+  (Contributed by Peter Bierma in :gh:`127604`.)
+
+
 fnmatch
 -------
 

Include/internal/pycore_faulthandler.h

@@ -56,6 +56,7 @@ struct _faulthandler_runtime_state {
 #ifdef MS_WINDOWS
         void *exc_handler;
 #endif
+        int c_stack;
     } fatal_error;
 
     struct {

Include/internal/pycore_traceback.h

@@ -99,6 +99,9 @@ extern int _PyTraceBack_Print(
 extern int _Py_WriteIndentedMargin(int, const char*, PyObject *);
 extern int _Py_WriteIndent(int, PyObject *);
 
+// Export for the faulthandler module
+PyAPI_FUNC(void) _Py_DumpStack(int fd);
+
 #ifdef __cplusplus
 }
 #endif

Lib/test/test_faulthandler.py

@@ -55,6 +55,13 @@ def temporary_filename():
     finally:
         os_helper.unlink(filename)
 
+
+ADDRESS_EXPR = "0x[0-9a-f]+"
+C_STACK_REGEX = [
+    r"Current thread's C stack trace \(most recent call first\):",
+    fr'(  Binary file ".+"(, at .*(\+|-){ADDRESS_EXPR})? \[{ADDRESS_EXPR}\])|(<.+>)'
+]
+
 class FaultHandlerTests(unittest.TestCase):
 
     def get_output(self, code, filename=None, fd=None):
@@ -103,6 +110,7 @@ def check_error(self, code, lineno, fatal_error, *,
                     fd=None, know_current_thread=True,
                     py_fatal_error=False,
                     garbage_collecting=False,
+                    c_stack=True,
                     function='<module>'):
         """
         Check that the fault handler for fatal errors is enabled and check the
@@ -134,6 +142,8 @@ def check_error(self, code, lineno, fatal_error, *,
             if garbage_collecting and not all_threads_disabled:
                 regex.append('  Garbage-collecting')
             regex.append(fr'  File "<string>", line {lineno} in {function}')
+        if c_stack:
+            regex.extend(C_STACK_REGEX)
         regex = '\n'.join(regex)
 
         if other_regex:
@@ -950,5 +960,35 @@ def run(self):
         _, exitcode = self.get_output(code)
         self.assertEqual(exitcode, 0)
 
+    def check_c_stack(self, output):
+        starting_line = output.pop(0)
+        self.assertRegex(starting_line, C_STACK_REGEX[0])
+        self.assertGreater(len(output), 0)
+
+        for line in output:
+            with self.subTest(line=line):
+                if line != '':  # Ignore trailing or leading newlines
+                    self.assertRegex(line, C_STACK_REGEX[1])
+
+
+    def test_dump_c_stack(self):
+        code = dedent("""
+        import faulthandler
+        faulthandler.dump_c_stack()
+        """)
+        output, exitcode = self.get_output(code)
+        self.assertEqual(exitcode, 0)
+        self.check_c_stack(output)
+
+
+    def test_dump_c_stack_file(self):
+        import tempfile
+
+        with tempfile.TemporaryFile("w+") as tmp:
+            faulthandler.dump_c_stack(file=tmp)
+            tmp.flush()  # Just in case
+            tmp.seek(0)
+            self.check_c_stack(tmp.read().split("\n"))
+
 if __name__ == "__main__":
     unittest.main()

Lib/test/test_inspect/test_inspect.py

@@ -5760,7 +5760,7 @@ def test_errno_module_has_signatures(self):
 
     def test_faulthandler_module_has_signatures(self):
         import faulthandler
-        unsupported_signature = {'dump_traceback', 'dump_traceback_later', 'enable'}
+        unsupported_signature = {'dump_traceback', 'dump_traceback_later', 'enable', 'dump_c_stack'}
         unsupported_signature |= {name for name in ['register']
                                   if hasattr(faulthandler, name)}
         self._test_module_has_signatures(faulthandler, unsupported_signature=unsupported_signature)

Misc/NEWS.d/next/Library/2024-12-21-13-31-55.gh-issue-127604.etL5mf.rst

@@ -0,0 +1,3 @@
+Add support for printing the C stack trace on systems that support it via
+:func:`faulthandler.dump_c_stack` or via the *c_stack* argument in
+:func:`faulthandler.enable`.

Modules/faulthandler.c

@@ -9,10 +9,10 @@
 #include "pycore_sysmodule.h"     // _PySys_GetRequiredAttr()
 #include "pycore_time.h"          // _PyTime_FromSecondsObject()
 #include "pycore_traceback.h"     // _Py_DumpTracebackThreads
-
 #ifdef HAVE_UNISTD_H
 #  include <unistd.h>             // _exit()
 #endif
+
 #include <signal.h>               // sigaction()
 #include <stdlib.h>               // abort()
 #if defined(HAVE_PTHREAD_SIGMASK) && !defined(HAVE_BROKEN_PTHREAD_SIGMASK) && defined(HAVE_PTHREAD_H)
@@ -210,6 +210,25 @@ faulthandler_dump_traceback(int fd, int all_threads,
     reentrant = 0;
 }
 
+static void
+faulthandler_dump_c_stack(int fd)
+{
+    static volatile int reentrant = 0;
+
+    if (reentrant) {
+        return;
+    }
+
+    reentrant = 1;
+
+    if (fatal_error.c_stack) {
+        PUTS(fd, "\n");
+        _Py_DumpStack(fd);
+    }
+
+    reentrant = 0;
+}
+
 static PyObject*
 faulthandler_dump_traceback_py(PyObject *self,
                                PyObject *args, PyObject *kwargs)
@@ -260,6 +279,33 @@ faulthandler_dump_traceback_py(PyObject *self,
     Py_RETURN_NONE;
 }
 
+static PyObject *
+faulthandler_dump_c_stack_py(PyObject *self,
+                             PyObject *args, PyObject *kwargs)
+{
+    static char *kwlist[] = {"file", NULL};
+    PyObject *file = NULL;
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs,
+        "|O:dump_c_stack", kwlist,
+        &file)) {
+        return NULL;
+    }
+
+    int fd = faulthandler_get_fileno(&file);
+    if (fd < 0) {
+        return NULL;
+    }
+
+    _Py_DumpStack(fd);
+
+    if (PyErr_CheckSignals()) {
+        return NULL;
+    }
+
+    Py_RETURN_NONE;
+}
+
 static void
 faulthandler_disable_fatal_handler(fault_handler_t *handler)
 {
@@ -350,6 +396,7 @@ faulthandler_fatal_error(int signum)
 
     faulthandler_dump_traceback(fd, deduce_all_threads(),
                                 fatal_error.interp);
+    faulthandler_dump_c_stack(fd);
 
     _Py_DumpExtensionModules(fd, fatal_error.interp);
 
@@ -425,6 +472,7 @@ faulthandler_exc_handler(struct _EXCEPTION_POINTERS *exc_info)
 
     faulthandler_dump_traceback(fd, deduce_all_threads(),
                                 fatal_error.interp);
+    faulthandler_dump_c_stack(fd);
 
     /* call the next exception handler */
     return EXCEPTION_CONTINUE_SEARCH;
@@ -519,14 +567,15 @@ faulthandler_enable(void)
 static PyObject*
 faulthandler_py_enable(PyObject *self, PyObject *args, PyObject *kwargs)
 {
-    static char *kwlist[] = {"file", "all_threads", NULL};
+    static char *kwlist[] = {"file", "all_threads", "c_stack", NULL};
     PyObject *file = NULL;
     int all_threads = 1;
     int fd;
+    int c_stack = 1;
     PyThreadState *tstate;
 
     if (!PyArg_ParseTupleAndKeywords(args, kwargs,
-        "|Op:enable", kwlist, &file, &all_threads))
+        "|Opp:enable", kwlist, &file, &all_threads, &c_stack))
         return NULL;
 
     fd = faulthandler_get_fileno(&file);
@@ -543,6 +592,7 @@ faulthandler_py_enable(PyObject *self, PyObject *args, PyObject *kwargs)
     fatal_error.fd = fd;
     fatal_error.all_threads = all_threads;
     fatal_error.interp = PyThreadState_GetInterpreter(tstate);
+    fatal_error.c_stack = c_stack;
 
     if (faulthandler_enable() < 0) {
         return NULL;
@@ -1238,6 +1288,10 @@ static PyMethodDef module_methods[] = {
      PyDoc_STR("dump_traceback($module, /, file=sys.stderr, all_threads=True)\n--\n\n"
                "Dump the traceback of the current thread, or of all threads "
                "if all_threads is True, into file.")},
+     {"dump_c_stack",
+      _PyCFunction_CAST(faulthandler_dump_c_stack_py), METH_VARARGS|METH_KEYWORDS,
+      PyDoc_STR("dump_c_stack($module, /, file=sys.stderr)\n--\n\n"
+              "Dump the C stack of the current thread.")},
     {"dump_traceback_later",
      _PyCFunction_CAST(faulthandler_dump_traceback_later), METH_VARARGS|METH_KEYWORDS,
      PyDoc_STR("dump_traceback_later($module, /, timeout, repeat=False, file=sys.stderr, exit=False)\n--\n\n"