pstack/Untitled at master · peadar/pstack · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
PSTACK(1)                                    BSD General Commands Manual                                    PSTACK(1)

NAME
     pstack — print stack traces from Linux processes and core files

SYNOPSIS
     pstack [-Aa] [-b delay] [-e executable] [-g directory] [-jlnstuvY] [-M frames] [-o file] [-r depth] [-x command]
            [-R] [-p] [executable | pid | core] ...
     pstack [-p] [-l] [-m] [-A] pid | core

DESCRIPTION
     pstack prints a stack trace for every thread in a running Linux process or an ELF core file.  It reads ELF,
     DWARF, and call-frame information directly, and can therefore unwind code compiled with -fno-omit-frame-pointer
     as well as code that omits frame pointers when suitable unwind data is present.

     The target operands may be PIDs or core files.  Normally, pstack infers the executable from the target.  An ELF
     file given as an operand that is not a core becomes the executable to use for the following targets, until an‐
     other executable is given.  The -e option sets that executable explicitly.

     More than one target may be supplied.  ELF and DWARF data shared by targets are cached for the duration of the
     invocation.

     Tracing a live process requires permission to use ptrace(2).  Distribution ptrace policies, containers, and the
     target's security settings may prevent tracing even when the tracer and target have the same UID.

     The options are as follows:

     -a, --args                      Attempt to show function argument values.  This is best-effort and requires us‐
                                     able DWARF information and readable target memory.

     -A, --all                       Show both CPython and native DWARF stack traces.  Without this option, -p prints
                                     only the Python trace.

     -b delay, --constant delay      Repeat the trace until interrupted, waiting delay seconds between iterations.
                                     delay may be non-integral.

     -D elf-file, --dwarf-dump elf-file
                                     Print DWARF information from elf-file as JSON and exit.

     -d elf-file, --elf-dump elf-file
                                     Print ELF information from elf-file as JSON and exit.

     -e executable, --executable executable
                                     Use executable as the executable image for subsequent PID or core operands.

     -g directory, --debug-dir directory
                                     Add directory to the search path for debug files for executables and shared li‐
                                     braries.

     -h, --help                      Print a usage summary and exit.

     -j, --json                      Write stack traces as JSON rather than text.  The JSON representation is in‐
                                     tended for automation, but consumers should pin the pstack version because its
                                     schema is not a separately versioned interface.

     -l, --locals                    Print local variables in Python stack frames.  This option is meaningful with
                                     -p.

     -M frames, --max-frames frames  Print at most frames stack frames for each thread.

     -m, --python-modules            Request the contents of Python modules while tracing.  This is retained for the
                                     legacy Python inspector and is generally not needed by the modern remote CPython
                                     inspector.

     -n, --no-ext-debug              Do not load external debug information.  In particular, do not follow debug
                                     links or look for separate debug images.

     --no-buildid                    Do not search for executable or debug files by GNU build ID.

     --no-local-files                Do not assume files visible to the tracer match the target's view, and do not
                                     open local files.

     -o file, --output file          Write normal output to file instead of standard output.

     -p, --python                    Print stack traces from compatible CPython interpreters found in the target.
                                     When built with modern Python remote-debugging support, this reads interpreter
                                     state from the target and uses version- and architecture-matched offset data.

     -r depth, --depth depth         Set the maximum nesting depth when rendering Python values.

     -R, --debuginfod                Use the debuginfod client to fetch missing executable and debug files by build
                                     ID.  This requires a usable libdebuginfod.so.1 at run time and a configured de‐
                                     buginfod service.

     -s, --no-src                    Do not include source file and line information in stack frames.

     -t, --no-threaddb               Do not use thread_db to enumerate pthreads; enumerate kernel LWPs instead.

     -v, --verbose                   Produce additional diagnostic output.  This option may be repeated.

     -V, --version                   Print the build version and exit.

     -x command, --command command   Run command as a subprocess and trace it when it receives a signal.  No target
                                     operand is required with this option.

     -Y, --no-die-names              Do not use DWARF DIE names for functions.

     --build-id-debugpath directory  Add directory to the build-ID search path for debug files.

     --build-id-exepath directory    Add directory to the build-ID search path for executable files.

     --clear-search-paths            Remove the built-in executable and debug-file search paths.  Use this before
                                     supplying explicit search paths to inspect files from another system.

     --exe-dir directory             Add directory to the search path for executables and shared libraries.

     --freeres                       Free all allocated memory before exit.  This is primarily useful when running
                                     pstack under Valgrind or a heap checker.

CPYTHON OFFSET DATA
     The modern CPython inspector requires an offset-data file named pyoff-<version>-<architecture>.json.  Installed
     data is searched through the current directory and XDG data locations.  Use pstack-mkpyoff with a target
     libpython to generate data for a compatible interpreter version that is not already provided.  Use -v to report
     the selected file.

DEBUG INFORMATION
     Unwinding normally needs .eh_frame or .debug_frame.  Symbols, source locations, and argument values improve when
     matching debug packages are available.  By default, pstack searches standard debug locations, follows
     .gnu_debuglink, and uses GNU build IDs.  The -g, --exe-dir, and build-ID-path options add search locations; al‐
     ternatively, -R can obtain missing data from debuginfod.

FILES
     /usr/lib/debug  A default root for separate debug files.

     /usr/lib/debug/.build-id
                     A default root for debug files located by build ID.

     /usr/lib/.build-id
                     A default root for executable files located by build ID.

EXIT STATUS
     The pstack utility exits 0 on success, and >0 if an error occurs.

SEE ALSO
     proc(5), ptrace(2)

AUTHORS
     Peter Edwards

Linux                                              August 25, 2026                                              Linux