gh-127604: Add C stack dumps to faulthandler

Doc/library/faulthandler.rst

@@ -66,10 +66,22 @@ 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 system doesn't support the C-level :manpage:`backtrace` or :manpage:`backtrace_symbols` functions,
+   then an error message is displayed instead of the C 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 +93,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 doesn't support it. See :func:`dump_c_stack` for
+   more information on compatibility.
+
    .. versionchanged:: 3.5
       Added support for passing file descriptor to this function.
 
@@ -91,6 +107,9 @@ Fault handler state
       The dump now mentions if a garbage collector collection is running
       if *all_threads* is true.
 
+   .. 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

@@ -367,6 +367,14 @@ errno
   (Contributed by James Roy in :gh:`126585`.)
 
 
+faulthandler
+------------
+
+* 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`.
+  (Contributed by Peter Bierma in :gh:`127604`.)
+
+
 fractions
 ---------
 

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 {

Lib/test/test_faulthandler.py

@@ -93,18 +93,20 @@ 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
         traceback from the child process output.
 
         Raise an error if the output doesn't match the expected format.
         """
+        address_expr = "0x[0-9a-f]+"
         if all_threads:
             if know_current_thread:
-                header = 'Current thread 0x[0-9a-f]+'
+                header = f'Current thread {address_expr}'
             else:
-                header = 'Thread 0x[0-9a-f]+'
+                header = f'Thread {address_expr}'
         else:
             header = 'Stack'
         regex = [f'^{fatal_error}']
@@ -115,6 +117,9 @@ def check_error(self, code, lineno, fatal_error, *,
         if garbage_collecting:
             regex.append('  Garbage-collecting')
         regex.append(fr'  File "<string>", line {lineno} in {function}')
+        if c_stack:
+            regex.append("Current thread's C stack (most recent call first):")
+            regex.append(r"  (\/.+\(\+.+\) \[0x[0-9a-f]+\])|(<.+>)")
         regex = '\n'.join(regex)
 
         if other_regex:

Lib/test/test_inspect/test_inspect.py

@@ -5726,7 +5726,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

@@ -10,6 +10,10 @@
 #ifdef HAVE_UNISTD_H
 #  include <unistd.h>             // _exit()
 #endif
+#ifdef HAVE_EXECINFO_H
+#  include <execinfo.h>           // backtrace(), backtrace_symbols()
+#endif
+
 #include <signal.h>               // sigaction()
 #include <stdlib.h>               // abort()
 #if defined(HAVE_PTHREAD_SIGMASK) && !defined(HAVE_BROKEN_PTHREAD_SIGMASK) && defined(HAVE_PTHREAD_H)
@@ -212,6 +216,80 @@ faulthandler_dump_traceback(int fd, int all_threads,
     reentrant = 0;
 }
 
+#ifdef HAVE_EXECINFO_H
+static void
+faulthandler_stack_dump_impl(int fd)
+{
+#define BACKTRACE_SIZE 16
+#define TRACEBACK_ENTRY_MAX_SIZE 256
+    void *callstack[BACKTRACE_SIZE];
+    int frames = backtrace(callstack, BACKTRACE_SIZE);
+    char **strings = backtrace_symbols(callstack, BACKTRACE_SIZE);
+    if (strings == NULL) {
+        PUTS(fd, "  <failed to get stack trace>\n");
+    }
+    else {
+        for (int i = 0; i < frames; ++i) {
+            char entry_str[TRACEBACK_ENTRY_MAX_SIZE];
+            snprintf(entry_str, TRACEBACK_ENTRY_MAX_SIZE, "  %s\n", strings[i]);
+            size_t length = strlen(entry_str) + 1;
+            if (length == TRACEBACK_ENTRY_MAX_SIZE) {
+                /* We exceeded the size, make it look prettier */
+
+                // Add ellipsis to last 3 characters
+                entry_str[TRACEBACK_ENTRY_MAX_SIZE - 5] = '.';
+                entry_str[TRACEBACK_ENTRY_MAX_SIZE - 4] = '.';
+                entry_str[TRACEBACK_ENTRY_MAX_SIZE - 3] = '.';
+
+                // Ensure trailing newline
+                entry_str[TRACEBACK_ENTRY_MAX_SIZE - 2] = '\n';
+
+                // Ensure that it's null-terminated
+                entry_str[TRACEBACK_ENTRY_MAX_SIZE - 1] = '\0';
+            }
+            _Py_write_noraise(fd, entry_str, length);
+        }
+
+        if (frames == BACKTRACE_SIZE) {
+            PUTS(fd, "  <truncated rest of calls>\n");
+        }
+    }
+#undef BACKTRACE_SIZE
+#undef TRACEBACK_ENTRY_MAX_SIZE
+}
+#else
+static void
+faulthandler_stack_dump_impl(int fd)
+{
+    PUTS(fd, "  <cannot get C stack on this system>\n");
+}
+#endif
+
+static void
+faulthandler_dump_c_stack_nocheck(int fd)
+{
+    PUTS(fd, "Current thread's C stack trace (most recent call first):\n");
+    faulthandler_stack_dump_impl(fd);
+}
+
+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");
+        faulthandler_dump_c_stack_nocheck(fd);
+    }
+
+    reentrant = 0;
+}
+
 static PyObject*
 faulthandler_dump_traceback_py(PyObject *self,
                                PyObject *args, PyObject *kwargs)
@@ -253,6 +331,32 @@ 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,
+        "|p:dump_c_stack", kwlist,
+        &file))
+        return NULL;
+
+    int fd = faulthandler_get_fileno(&file);
+    if (fd < 0) {
+        return NULL;
+    }
+
+    faulthandler_dump_c_stack_nocheck(fd);
+
+    if (PyErr_CheckSignals()) {
+        return NULL;
+    }
+
+    Py_RETURN_NONE;
+}
+
 static void
 faulthandler_disable_fatal_handler(fault_handler_t *handler)
 {
@@ -322,6 +426,7 @@ faulthandler_fatal_error(int signum)
 
     faulthandler_dump_traceback(fd, fatal_error.all_threads,
                                 fatal_error.interp);
+    faulthandler_dump_c_stack(fd);
 
     _Py_DumpExtensionModules(fd, fatal_error.interp);
 
@@ -398,6 +503,7 @@ faulthandler_exc_handler(struct _EXCEPTION_POINTERS *exc_info)
 
     faulthandler_dump_traceback(fd, fatal_error.all_threads,
                                 fatal_error.interp);
+    faulthandler_dump_c_stack(fd);
 
     /* call the next exception handler */
     return EXCEPTION_CONTINUE_SEARCH;
@@ -492,14 +598,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);
@@ -515,6 +622,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;
@@ -1205,6 +1313,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"

Tools/c-analyzer/cpython/ignored.tsv

@@ -161,6 +161,7 @@ Python/sysmodule.c	-	_preinit_xoptions	-
 # thread-safety
 # XXX need race protection?
 Modules/faulthandler.c	faulthandler_dump_traceback	reentrant	-
+Modules/faulthandler.c	faulthandler_dump_c_stack	reentrant	-
 Python/pylifecycle.c	_Py_FatalErrorFormat	reentrant	-
 Python/pylifecycle.c	fatal_error	reentrant	-
 

configure.ac

@@ -2929,7 +2929,7 @@ AC_DEFINE([STDC_HEADERS], [1],
 
 # checks for header files
 AC_CHECK_HEADERS([ \
-  alloca.h asm/types.h bluetooth.h conio.h direct.h dlfcn.h endian.h errno.h fcntl.h grp.h \
+  alloca.h asm/types.h bluetooth.h conio.h direct.h dlfcn.h endian.h errno.h execinfo.h fcntl.h grp.h \
   io.h langinfo.h libintl.h libutil.h linux/auxvec.h sys/auxv.h linux/fs.h linux/limits.h linux/memfd.h \
   linux/netfilter_ipv4.h linux/random.h linux/soundcard.h linux/sched.h \
   linux/tipc.h linux/wait.h netdb.h net/ethernet.h netinet/in.h netpacket/packet.h poll.h process.h pthread.h pty.h \

pyconfig.h.in

@@ -331,6 +331,9 @@
 /* Define if you have the 'eventfd' function. */
 #undef HAVE_EVENTFD
 
+/* Define to 1 if you have the <execinfo.h> header file. */
+#undef HAVE_EXECINFO_H
+
 /* Define to 1 if you have the `execv' function. */
 #undef HAVE_EXECV