.Dd August 25, 2026
.Dt PSTACK 1
.Os Linux
.Sh NAME
.Nm pstack
.Nd print stack traces from Linux processes and core files
.Sh SYNOPSIS
.Nm
.Op Fl Aa
.Op Fl b Ar delay
.Op Fl e Ar executable
.Op Fl g Ar directory
.Op Fl jlnstuvY
.Op Fl M Ar frames
.Op Fl o Ar file
.Op Fl r Ar depth
.Op Fl x Ar command
.Op Fl R
.Op Fl p
.Op Ar executable | pid | core
.Ar ...
.Nm
.Op Fl p
.Op Fl l
.Op Fl m
.Op Fl A
.Ar pid | core
.Sh DESCRIPTION
.Nm
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
.Fl fno-omit-frame-pointer
as well as code that omits frame pointers when suitable unwind data is present.
.Pp
The target operands may be PIDs or core files.
Normally,
.Nm
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 another executable is given.
The
.Fl e
option sets that executable explicitly.
.Pp
More than one target may be supplied.
ELF and DWARF data shared by targets are cached for the duration of the
invocation.
.Pp
Tracing a live process requires permission to use
.Xr 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.
.Pp
The options are as follows:
.Bl -tag -width "--build-id-debugpath directory"
.It Fl a , Fl -args
Attempt to show function argument values.
This is best-effort and requires usable DWARF information and readable target
memory.
.It Fl A , Fl -all
Show both CPython and native DWARF stack traces.
Without this option,
.Fl p
prints only the Python trace.
.It Fl b Ar delay , Fl -constant Ar delay
Repeat the trace until interrupted, waiting
.Ar delay
seconds between iterations.
.Ar delay
may be non-integral.
.It Fl D Ar elf-file , Fl -dwarf-dump Ar elf-file
Print DWARF information from
.Ar elf-file
as JSON and exit.
.It Fl d Ar elf-file , Fl -elf-dump Ar elf-file
Print ELF information from
.Ar elf-file
as JSON and exit.
.It Fl e Ar executable , Fl -executable Ar executable
Use
.Ar executable
as the executable image for subsequent PID or core operands.
.It Fl g Ar directory , Fl -debug-dir Ar directory
Add
.Ar directory
to the search path for debug files for executables and shared libraries.
.It Fl h , Fl -help
Print a usage summary and exit.
.It Fl j , Fl -json
Write stack traces as JSON rather than text.
The JSON representation is intended for automation, but consumers should pin
the
.Nm
version because its schema is not a separately versioned interface.
.It Fl l , Fl -locals
Print local variables in Python stack frames.
This option is meaningful with
.Fl p .
.It Fl M Ar frames , Fl -max-frames Ar frames
Print at most
.Ar frames
stack frames for each thread.
.It Fl m , Fl -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.
.It Fl n , Fl -no-ext-debug
Do not load external debug information.
In particular, do not follow debug links or look for separate debug images.
.It Fl -no-buildid
Do not search for executable or debug files by GNU build ID.
.It Fl -no-local-files
Do not assume files visible to the tracer match the target's view, and do not
open local files.
.It Fl o Ar file , Fl -output Ar file
Write normal output to
.Ar file
instead of standard output.
.It Fl p , Fl -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.
.It Fl r Ar depth , Fl -depth Ar depth
Set the maximum nesting depth when rendering Python values.
.It Fl R , Fl -debuginfod
Use the debuginfod client to fetch missing executable and debug files by build
ID.
This requires a usable
.Pa libdebuginfod.so.1
at run time and a configured debuginfod service.
.It Fl s , Fl -no-src
Do not include source file and line information in stack frames.
.It Fl t , Fl -no-threaddb
Do not use
.Li thread_db
to enumerate pthreads; enumerate kernel LWPs instead.
.It Fl v , Fl -verbose
Produce additional diagnostic output.
This option may be repeated.
.It Fl V , Fl -version
Print the build version and exit.
.It Fl x Ar command , Fl -command Ar command
Run
.Ar command
as a subprocess and trace it when it receives a signal.
No target operand is required with this option.
.It Fl Y , Fl -no-die-names
Do not use DWARF DIE names for functions.
.It Fl -build-id-debugpath Ar directory
Add
.Ar directory
to the build-ID search path for debug files.
.It Fl -build-id-exepath Ar directory
Add
.Ar directory
to the build-ID search path for executable files.
.It Fl -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.
.It Fl -exe-dir Ar directory
Add
.Ar directory
to the search path for executables and shared libraries.
.It Fl -freeres
Free all allocated memory before exit.
This is primarily useful when running
.Nm
under Valgrind or a heap checker.
.El
.Sh CPYTHON OFFSET DATA
The modern CPython inspector requires an offset-data file named
.Pa pyoff-<version>-<architecture>.json .
Installed data is searched through the current directory and XDG data locations.
Use
.Nm pstack-mkpyoff
with a target
.Pa libpython
to generate data for a compatible interpreter version that is not already
provided.
Use
.Fl v
to report the selected file.
.Sh DEBUG INFORMATION
Unwinding normally needs
.Pa .eh_frame
or
.Pa .debug_frame .
Symbols, source locations, and argument values improve when matching debug
packages are available.
By default,
.Nm
searches standard debug locations, follows
.Pa .gnu_debuglink ,
and uses GNU build IDs.
The
.Fl g ,
.Fl -exe-dir ,
and build-ID-path options add search locations; alternatively,
.Fl R
can obtain missing data from debuginfod.
.Sh FILES
.Bl -tag -width "/usr/lib/debug"
.It Pa /usr/lib/debug
A default root for separate debug files.
.It Pa /usr/lib/debug/.build-id
A default root for debug files located by build ID.
.It Pa /usr/lib/.build-id
A default root for executable files located by build ID.
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr proc 5 ,
.Xr ptrace 2
.Sh AUTHORS
.An Peter Edwards