python · pablogsal · Apr 21, 2025 · Dec 21, 2024 · Dec 21, 2024 · Dec 21, 2024
diff --git a/Doc/library/faulthandler.rst b/Doc/library/faulthandler.rst
@@ -66,10 +66,23 @@ 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 does not support the C-level :manpage:`backtrace(3)`
+   or :manpage:`backtrace_symbols(3)` 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 +94,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 +112,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

@@ -399,6 +399,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
 ---------
 

diff --git a/Include/internal/pycore_faulthandler.h b/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 {

diff --git a/Include/internal/pycore_traceback.h b/Include/internal/pycore_traceback.h
@@ -100,6 +100,10 @@ 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

diff --git a/Lib/test/test_faulthandler.py b/Lib/test/test_faulthandler.py
@@ -93,22 +93,24 @@ 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]+"
         all_threads_disabled = (
             all_threads
             and (not sys._is_gil_enabled())
         )
         if all_threads and not all_threads_disabled:
             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}']
@@ -118,12 +120,17 @@ def check_error(self, code, lineno, fatal_error, *,
         if all_threads_disabled and not py_fatal_error:
             regex.append("<Cannot show all threads while the GIL is disabled>")
         regex.append(fr'{header} \(most recent call first\):')
+        if garbage_collecting:
+            regex.append('  Garbage-collecting')
         if support.Py_GIL_DISABLED and py_fatal_error and not know_current_thread:
             regex.append("  <tstate is freed>")
         else:
             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.append("Current thread's C stack (most recent call first):")
+            regex.append(r"  (\/.+\(\+.+\) \[0x[0-9a-f]+\])|(<.+>)")
         regex = '\n'.join(regex)
 
         if other_regex:

diff --git a/Lib/test/test_inspect/test_inspect.py b/Lib/test/test_inspect/test_inspect.py
@@ -5723,7 +5723,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)

diff --git a/Misc/NEWS.d/next/Library/2024-12-21-13-31-55.gh-issue-127604.etL5mf.rst b/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`.
diff --git a/Modules/faulthandler.c b/Modules/faulthandler.c
@@ -11,6 +11,7 @@
 #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)
@@ -218,6 +219,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)
@@ -264,6 +284,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;
+    }
+
+    _Py_DumpStack(fd);
+
+    if (PyErr_CheckSignals()) {
+        return NULL;
+    }
+
+    Py_RETURN_NONE;
+}
+
 static void
 faulthandler_disable_fatal_handler(fault_handler_t *handler)
 {
@@ -354,6 +400,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);
 
@@ -430,6 +477,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;
@@ -524,14 +572,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);
@@ -547,6 +596,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;
@@ -1237,6 +1287,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"

diff --git a/Python/traceback.c b/Python/traceback.c
@@ -21,6 +21,9 @@
 #ifdef HAVE_UNISTD_H
 #  include <unistd.h>             // lseek()
 #endif
+#ifdef HAVE_EXECINFO_H
+#  include <execinfo.h>           // backtrace(), backtrace_symbols()
+#endif
 
 
 #define OFF(x) offsetof(PyTracebackObject, x)
@@ -1101,3 +1104,68 @@ _Py_DumpTracebackThreads(int fd, PyInterpreterState *interp,
     return NULL;
 }
 
+#define TRACEBACK_ENTRY_MAX_SIZE 256
+
+static void
+format_entry(char *entry_str, const char *the_entry, Py_ssize_t *length_ptr)
+{
+    int length = PyOS_snprintf(entry_str, TRACEBACK_ENTRY_MAX_SIZE, "  %s\n", the_entry);
+    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';
+    }
+
+    *length_ptr = (Py_ssize_t)length;
+}
+
+/* This is for faulthandler.
+ * Apparently, backtrace() doesn't play well across DLL boundaries on macOS */
+#if defined(HAVE_EXECINFO_H) && defined(HAVE_BACKTRACE) && defined(HAVE_BACKTRACE_SYMBOLS)
+void
+_Py_DumpStack(int fd)
+{
+#define BACKTRACE_SIZE 32
+    PUTS(fd, "Current thread's C stack trace (most recent call first):\n");
+    void *callstack[BACKTRACE_SIZE];
+    int frames = backtrace(callstack, BACKTRACE_SIZE);
+    if (frames == 0) {
+        // Some systems won't return anything for the stack trace
+        PUTS(fd, "  <system returned no stack trace>\n");
+        return;
+    }
+
+    char **strings = backtrace_symbols(callstack, BACKTRACE_SIZE);
+    if (strings == NULL) {
+        PUTS(fd, "  <not enough memory to get stack trace>\n");
+        return;
+    }
+    for (int i = 0; i < frames; ++i) {
+        char entry_str[TRACEBACK_ENTRY_MAX_SIZE];
+        Py_ssize_t length;
+        format_entry(entry_str, strings[i], &length);
+        _Py_write_noraise(fd, entry_str, length);
+    }
+
+    if (frames == BACKTRACE_SIZE) {
+        PUTS(fd, "  <truncated rest of calls>\n");
+    }
+
+    free(strings);
+#undef BACKTRACE_SIZE
+#undef TRACEBACK_ENTRY_MAX_SIZE
+}
+#else
+void
+_Py_DumpStack(int fd)
+{
+    PUTS(fd, "Current thread's C stack trace (most recent call first):\n");
+    PUTS(fd, "  <cannot get C stack on this system>\n");
+}
+#endif
@@ -164,6 +164,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	-