python3.13/internal/pycore_traceback.h

0001 #ifndef Py_INTERNAL_TRACEBACK_H
0002 #define Py_INTERNAL_TRACEBACK_H
0003 #ifdef __cplusplus
0004 extern "C" {
0005 #endif
0006
0007 #ifndef Py_BUILD_CORE
0008 #  error "this header requires Py_BUILD_CORE define"
0009 #endif
0010
0011 // Export for '_ctypes' shared extension
0012 PyAPI_FUNC(int) _Py_DisplaySourceLine(PyObject *, PyObject *, int, int, int *, PyObject **);
0013
0014 // Export for 'pyexact' shared extension
0015 PyAPI_FUNC(void) _PyTraceback_Add(const char *, const char *, int);
0016
0017 /* Write the Python traceback into the file 'fd'. For example:
0018
0019        Traceback (most recent call first):
0020          File "xxx", line xxx in <xxx>
0021          File "xxx", line xxx in <xxx>
0022          ...
0023          File "xxx", line xxx in <xxx>
0024
0025    This function is written for debug purpose only, to dump the traceback in
0026    the worst case: after a segmentation fault, at fatal error, etc. That's why,
0027    it is very limited. Strings are truncated to 100 characters and encoded to
0028    ASCII with backslashreplace. It doesn't write the source code, only the
0029    function name, filename and line number of each frame. Write only the first
0030    100 frames: if the traceback is truncated, write the line " ...".
0031
0032    This function is signal safe. */
0033
0034 extern void _Py_DumpTraceback(
0035     int fd,
0036     PyThreadState *tstate);
0037
0038 /* Write the traceback of all threads into the file 'fd'. current_thread can be
0039    NULL.
0040
0041    Return NULL on success, or an error message on error.
0042
0043    This function is written for debug purpose only. It calls
0044    _Py_DumpTraceback() for each thread, and so has the same limitations. It
0045    only write the traceback of the first 100 threads: write "..." if there are
0046    more threads.
0047
0048    If current_tstate is NULL, the function tries to get the Python thread state
0049    of the current thread. It is not an error if the function is unable to get
0050    the current Python thread state.
0051
0052    If interp is NULL, the function tries to get the interpreter state from
0053    the current Python thread state, or from
0054    _PyGILState_GetInterpreterStateUnsafe() in last resort.
0055
0056    It is better to pass NULL to interp and current_tstate, the function tries
0057    different options to retrieve this information.
0058
0059    This function is signal safe. */
0060
0061 extern const char* _Py_DumpTracebackThreads(
0062     int fd,
0063     PyInterpreterState *interp,
0064     PyThreadState *current_tstate);
0065
0066 /* Write a Unicode object into the file descriptor fd. Encode the string to
0067    ASCII using the backslashreplace error handler.
0068
0069    Do nothing if text is not a Unicode object. The function accepts Unicode
0070    string which is not ready (PyUnicode_WCHAR_KIND).
0071
0072    This function is signal safe. */
0073 extern void _Py_DumpASCII(int fd, PyObject *text);
0074
0075 /* Format an integer as decimal into the file descriptor fd.
0076
0077    This function is signal safe. */
0078 extern void _Py_DumpDecimal(
0079     int fd,
0080     size_t value);
0081
0082 /* Format an integer as hexadecimal with width digits into fd file descriptor.
0083    The function is signal safe. */
0084 extern void _Py_DumpHexadecimal(
0085     int fd,
0086     uintptr_t value,
0087     Py_ssize_t width);
0088
0089 extern PyObject* _PyTraceBack_FromFrame(
0090     PyObject *tb_next,
0091     PyFrameObject *frame);
0092
0093 #define EXCEPTION_TB_HEADER "Traceback (most recent call last):\n"
0094 #define EXCEPTION_GROUP_TB_HEADER "Exception Group Traceback (most recent call last):\n"
0095
0096 /* Write the traceback tb to file f. Prefix each line with
0097    indent spaces followed by the margin (if it is not NULL). */
0098 extern int _PyTraceBack_Print(
0099     PyObject *tb, const char *header, PyObject *f);
0100 extern int _Py_WriteIndentedMargin(int, const char*, PyObject *);
0101 extern int _Py_WriteIndent(int, PyObject *);
0102
0103 #ifdef __cplusplus
0104 }
0105 #endif
0106 #endif /* !Py_INTERNAL_TRACEBACK_H */