@@ -1348,3 +1348,67 @@ Tracebacks
13481348
13491349 This function returns ``0 `` on success, and returns ``-1 `` with an
13501350 exception set on failure.
1351+
1352+ .. c :function :: const char * PyUnstable_DumpTraceback (int fd, PyThreadState *tstate)
1353+
1354+ Write a trace of the Python stack in *tstate * into the file *fd *. The format
1355+ looks like::
1356+
1357+ Traceback (most recent call first):
1358+ File "xxx", line xxx in <xxx>
1359+ File "xxx", line xxx in <xxx>
1360+ ...
1361+ File "xxx", line xxx in <xxx>
1362+
1363+ This function is meant to debug situations such as segfaults, fatal errors,
1364+ and similar. The file and function names it outputs are encoded to ASCII with
1365+ backslashreplace and truncated to 500 characters. It writes only the first
1366+ 100 frames; further frames are truncated with the line ``... ``.
1367+
1368+ This function will return ``NULL `` on success, or an error message on error.
1369+
1370+ This function is intended for use in crash scenarios such as signal handlers
1371+ for SIGSEGV, where the interpreter may be in an inconsistent state. Given
1372+ that it reads interpreter data structures that may be partially modified, the
1373+ function might produce incomplete output or it may even crash itself.
1374+
1375+ The caller does not need to hold an :term: `attached thread state `, nor does
1376+ *tstate * need to be attached.
1377+
1378+ .. versionadded :: 3.15
1379+
1380+ .. c :function :: const char * PyUnstable_DumpTracebackThreads (int fd, PyInterpreterState *interp, PyThreadState *current_tstate, Py_ssize_t max_threads)
1381+
1382+ Write the traces of all Python threads in *interp * into the file *fd *.
1383+
1384+ If *interp * is ``NULL `` then this function will try to identify the current
1385+ interpreter using thread-specific storage. If it cannot, it will return an
1386+ error.
1387+
1388+ If *current_tstate * is not ``NULL `` then it will be used to identify what the
1389+ current thread is in the written output. If it is ``NULL `` then this function
1390+ will identify the current thread using thread-specific storage. It is not an
1391+ error if the function is unable to get the current Python thread state.
1392+
1393+ This function will return ``NULL `` on success, or an error message on error.
1394+
1395+ This function is meant to debug debug situations such as segfaults, fatal
1396+ errors, and similar. It calls :c:func: `PyUnstable_DumpTraceback ` for each
1397+ thread. It only writes the tracebacks of the first *max_threads * threads,
1398+ further output is truncated with the line ``... ``. If *max_threads * is 0, the
1399+ function will use a default value of 100 for the argument.
1400+
1401+ This function is intended for use in crash scenarios such as signal handlers
1402+ for SIGSEGV, where the interpreter may be in an inconsistent state. Given
1403+ that it reads interpreter data structures that may be partially modified, the
1404+ function might produce incomplete output or it may even crash itself.
1405+
1406+ The caller does not need to hold an :term: `attached thread state `, nor does
1407+ *current_tstate * need to be attached.
1408+
1409+ .. warning ::
1410+ On the :term: `free-threaded build `, this function is not thread-safe. If
1411+ another thread deletes its :term: `thread state ` while this function is being
1412+ called, the process will likely crash.
1413+
1414+ .. versionadded :: 3.15
0 commit comments