Merge branch 'main' into dump-traceback

Author: alexmalyshev

Doc/c-api/exceptions.rst

@@ -1346,3 +1346,67 @@ Tracebacks
 
    This function returns ``0`` on success, and returns ``-1`` with an
    exception set on failure.
+
+.. c:function:: const char* PyUnstable_DumpTraceback(int fd, PyThreadState *tstate)
+
+   Write a trace of the Python stack in *tstate* into the file *fd*.  The format
+   looks like::
+
+      Traceback (most recent call first):
+            File "xxx", line xxx in <xxx>
+            File "xxx", line xxx in <xxx>
+            ...
+            File "xxx", line xxx in <xxx>
+
+   This function is meant to debug situations such as segfaults, fatal errors,
+   and similar. The file and function names it outputs are encoded to ASCII with
+   backslashreplace and truncated to 500 characters. It writes only the first
+   100 frames; further frames are truncated with the line ``...``.
+
+   This function will return ``NULL`` on success, or an error message on error.
+
+   This function is intended for use in crash scenarios such as signal handlers
+   for SIGSEGV, where the interpreter may be in an inconsistent state. Given
+   that it reads interpreter data structures that may be partially modified, the
+   function might produce incomplete output or it may even crash itself.
+
+   The caller does not need to hold an :term:`attached thread state`, nor does
+   *tstate* need to be attached.
+
+   .. versionadded:: next
+
+.. c:function:: const char* PyUnstable_DumpTracebackThreads(int fd, PyInterpreterState *interp, PyThreadState *current_tstate)
+
+   Write the traces of all Python threads in *interp* into the file *fd*.
+
+   If *interp* is ``NULL`` then this function will try to identify the current
+   interpreter using thread-specific storage. If it cannot, it will return an
+   error.
+
+   If *current_tstate* is not ``NULL`` then it will be used to identify what the
+   current thread is in the written output. If it is ``NULL`` then this function
+   will identify the current thread using thread-specific storage. It is not an
+   error if the function is unable to get the current Python thread state.
+
+   This function will return ``NULL`` on success, or an error message on error.
+   It will also write this error message to *fd*.
+
+   This function is meant to debug debug situations such as segfaults, fatal
+   errors, and similar. It calls :c:func:`PyUnstable_DumpTraceback` for each
+   thread. It only writes the tracebacks of the first 100 threads, further
+   output is truncated with the line ``...``.
+
+   This function is intended for use in crash scenarios such as signal handlers
+   for SIGSEGV, where the interpreter may be in an inconsistent state. Given
+   that it reads interpreter data structures that may be partially modified, the
+   function might produce incomplete output or it may even crash itself.
+
+   The caller does not need to hold an :term:`attached thread state`, nor does
+   *current_tstate* need to be attached.
+
+   .. warning::
+      On the :term:`free-threaded build`, this function is not thread-safe. If
+      another thread deletes its :term:`thread state` while this function is being
+      called, the process will likely crash.
+
+   .. versionadded:: next

Doc/whatsnew/3.15.rst

@@ -1788,6 +1788,11 @@ New features
   Python 3.14.
   (Contributed by Victor Stinner in :gh:`142417`.)
 
+* Add :c:func:`PyUnstable_DumpTraceback` and
+  :c:func:`PyUnstable_DumpTracebackThreads` functions to safely output Python
+  stacktraces.
+  (Contributed by Alex Malyshev in :gh:`145559`.)
+
 Changed C APIs
 --------------
 

Include/cpython/traceback.h

@@ -11,3 +11,10 @@ struct _traceback {
     int tb_lasti;
     int tb_lineno;
 };
+
+PyAPI_FUNC(const char*) PyUnstable_DumpTraceback(int fd, PyThreadState *tstate);
+
+PyAPI_FUNC(const char*) PyUnstable_DumpTracebackThreads(
+    int fd,
+    PyInterpreterState *interp,
+    PyThreadState *current_tstate);

Include/internal/pycore_traceback.h

@@ -14,55 +14,6 @@ PyAPI_FUNC(int) _Py_DisplaySourceLine(PyObject *, PyObject *, int, int, int *, P
 // Export for 'pyexact' shared extension
 PyAPI_FUNC(void) _PyTraceback_Add(const char *, const char *, int);
 
-/* Write the Python traceback into the file 'fd'. For example:
-
-       Traceback (most recent call first):
-         File "xxx", line xxx in <xxx>
-         File "xxx", line xxx in <xxx>
-         ...
-         File "xxx", line xxx in <xxx>
-
-   This function is written for debug purpose only, to dump the traceback in
-   the worst case: after a segmentation fault, at fatal error, etc. That's why,
-   it is very limited. Strings are truncated to 100 characters and encoded to
-   ASCII with backslashreplace. It doesn't write the source code, only the
-   function name, filename and line number of each frame. Write only the first
-   100 frames: if the traceback is truncated, write the line " ...".
-
-   This function is signal safe. */
-
-extern void _Py_DumpTraceback(
-    int fd,
-    PyThreadState *tstate);
-
-/* Write the traceback of all threads into the file 'fd'. current_thread can be
-   NULL.
-
-   Return NULL on success, or an error message on error.
-
-   This function is written for debug purpose only. It calls
-   _Py_DumpTraceback() for each thread, and so has the same limitations. It
-   only write the traceback of the first 100 threads: write "..." if there are
-   more threads.
-
-   If current_tstate is NULL, the function tries to get the Python thread state
-   of the current thread. It is not an error if the function is unable to get
-   the current Python thread state.
-
-   If interp is NULL, the function tries to get the interpreter state from
-   the current Python thread state, or from
-   _PyGILState_GetInterpreterStateUnsafe() in last resort.
-
-   It is better to pass NULL to interp and current_tstate, the function tries
-   different options to retrieve this information.
-
-   This function is signal safe. */
-
-extern const char* _Py_DumpTracebackThreads(
-    int fd,
-    PyInterpreterState *interp,
-    PyThreadState *current_tstate);
-
 /* Write a Unicode object into the file descriptor fd. Encode the string to
    ASCII using the backslashreplace error handler.
 

Misc/NEWS.d/next/C_API/2026-03-06-21-50-48.gh-issue-145559.AiXgHq.rst

@@ -0,0 +1 @@
+Rename ``_Py_DumpTraceback`` and ``_Py_DumpTracebackThreads`` to :c:func:`PyUnstable_DumpTraceback` and :c:func:`PyUnstable_DumpTracebackThreads`.

Modules/faulthandler.c

@@ -7,7 +7,7 @@
 #include "pycore_runtime.h"       // _Py_ID()
 #include "pycore_signal.h"        // Py_NSIG
 #include "pycore_time.h"          // _PyTime_FromSecondsObject()
-#include "pycore_traceback.h"     // _Py_DumpTracebackThreads
+#include "pycore_traceback.h"     // _Py_DumpStack()
 #ifdef HAVE_UNISTD_H
 #  include <unistd.h>             // _exit()
 #endif
@@ -205,14 +205,15 @@ faulthandler_dump_traceback(int fd, int all_threads,
     PyThreadState *tstate = PyGILState_GetThisThreadState();
 
     if (all_threads == 1) {
-        (void)_Py_DumpTracebackThreads(fd, NULL, tstate);
+        (void)PyUnstable_DumpTracebackThreads(fd, NULL, tstate);
     }
     else {
         if (all_threads == FT_IGNORE_ALL_THREADS) {
             PUTS(fd, "<Cannot show all threads while the GIL is disabled>\n");
         }
-        if (tstate != NULL)
-            _Py_DumpTraceback(fd, tstate);
+        if (tstate != NULL) {
+            PyUnstable_DumpTraceback(fd, tstate);
+        }
     }
 
     reentrant = 0;
@@ -273,17 +274,18 @@ faulthandler_dump_traceback_py_impl(PyObject *module, PyObject *file,
         /* gh-128400: Accessing other thread states while they're running
          * isn't safe if those threads are running. */
         _PyEval_StopTheWorld(interp);
-        errmsg = _Py_DumpTracebackThreads(fd, NULL, tstate);
+        errmsg = PyUnstable_DumpTracebackThreads(fd, NULL, tstate);
         _PyEval_StartTheWorld(interp);
-        if (errmsg != NULL) {
-            PyErr_SetString(PyExc_RuntimeError, errmsg);
-            Py_XDECREF(file);
-            return NULL;
-        }
     }
     else {
-        _Py_DumpTraceback(fd, tstate);
+        errmsg = PyUnstable_DumpTraceback(fd, tstate);
+    }
+    if (errmsg != NULL) {
+      PyErr_SetString(PyExc_RuntimeError, errmsg);
+      Py_XDECREF(file);
+      return NULL;
     }
+
     Py_XDECREF(file);
 
     if (PyErr_CheckSignals())
@@ -703,7 +705,7 @@ faulthandler_thread(void *unused)
 
         (void)_Py_write_noraise(thread.fd, thread.header, (int)thread.header_len);
 
-        errmsg = _Py_DumpTracebackThreads(thread.fd, thread.interp, NULL);
+        errmsg = PyUnstable_DumpTracebackThreads(thread.fd, thread.interp, NULL);
         ok = (errmsg == NULL);
 
         if (thread.exit)

Platforms/emscripten/node_entry.mjs

@@ -57,6 +57,6 @@ try {
   // Show JavaScript exception and traceback
   console.warn(e);
   // Show Python exception and traceback
-  Module.__Py_DumpTraceback(2, Module._PyGILState_GetThisThreadState());
+  Module.PyUnstable_DumpTraceback(2, Module._PyGILState_GetThisThreadState());
   process.exit(1);
 }

Platforms/emscripten/web_example_pyrepl_jspi/src.mjs

@@ -189,6 +189,6 @@ try {
   // Show JavaScript exception and traceback
   console.warn(e);
   // Show Python exception and traceback
-  Module.__Py_DumpTraceback(2, Module._PyGILState_GetThisThreadState());
+  Module.PyUnstable_DumpTraceback(2, Module._PyGILState_GetThisThreadState());
   process.exit(1);
 }

Python/pylifecycle.c

@@ -3261,9 +3261,9 @@ _Py_FatalError_DumpTracebacks(int fd, PyInterpreterState *interp,
 
     /* display the current Python stack */
 #ifndef Py_GIL_DISABLED
-    _Py_DumpTracebackThreads(fd, interp, tstate);
+    PyUnstable_DumpTracebackThreads(fd, interp, tstate);
 #else
-    _Py_DumpTraceback(fd, tstate);
+    PyUnstable_DumpTraceback(fd, tstate);
 #endif
 }
 

Python/traceback.c

@@ -1167,10 +1167,11 @@ dump_traceback(int fd, PyThreadState *tstate, int write_header)
 
    The caller is responsible to call PyErr_CheckSignals() to call Python signal
    handlers if signals were received. */
-void
-_Py_DumpTraceback(int fd, PyThreadState *tstate)
+const char*
+PyUnstable_DumpTraceback(int fd, PyThreadState *tstate)
 {
     dump_traceback(fd, tstate, 1);
+    return NULL;
 }
 
 #if defined(HAVE_PTHREAD_GETNAME_NP) || defined(HAVE_PTHREAD_GET_NAME_NP)
@@ -1257,18 +1258,26 @@ write_thread_id(int fd, PyThreadState *tstate, int is_current)
     PUTS(fd, " (most recent call first):\n");
 }
 
+/* Write an error string and also return it at the same time. */
+static const char*
+dump_error(int fd, const char *msg)
+{
+    PUTS(fd, msg);
+    return msg;
+}
+
 /* Dump the traceback of all Python threads into fd. Use write() to write the
    traceback and retry if write() is interrupted by a signal (failed with
    EINTR), but don't call the Python signal handler.
 
    The caller is responsible to call PyErr_CheckSignals() to call Python signal
    handlers if signals were received. */
 const char* _Py_NO_SANITIZE_THREAD
-_Py_DumpTracebackThreads(int fd, PyInterpreterState *interp,
-                         PyThreadState *current_tstate)
+PyUnstable_DumpTracebackThreads(int fd, PyInterpreterState *interp,
+                                PyThreadState *current_tstate)
 {
     if (current_tstate == NULL) {
-        /* _Py_DumpTracebackThreads() is called from signal handlers by
+        /* PyUnstable_DumpTracebackThreads() is called from signal handlers by
            faulthandler.
 
            SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL are synchronous signals
@@ -1283,15 +1292,15 @@ _Py_DumpTracebackThreads(int fd, PyInterpreterState *interp,
     }
 
     if (current_tstate != NULL && tstate_is_freed(current_tstate)) {
-        return "tstate is freed";
+        return dump_error(fd, "tstate is freed");
     }
 
     if (interp == NULL) {
         if (current_tstate == NULL) {
             interp = _PyGILState_GetInterpreterStateUnsafe();
             if (interp == NULL) {
                 /* We need the interpreter state to get Python threads */
-                return "unable to get the interpreter state";
+                return dump_error(fd, "unable to get the interpreter state");
             }
         }
         else {
@@ -1301,13 +1310,13 @@ _Py_DumpTracebackThreads(int fd, PyInterpreterState *interp,
     assert(interp != NULL);
 
     if (interp_is_freed(interp)) {
-        return "interp is freed";
+        return dump_error(fd, "interp is freed");
     }
 
     /* Get the current interpreter from the current thread */
     PyThreadState *tstate = PyInterpreterState_ThreadHead(interp);
     if (tstate == NULL)
-        return "unable to get the thread head state";
+        return dump_error(fd, "unable to get the thread head state");
 
     /* Dump the traceback of each thread */
     unsigned int nthreads = 0;