pstack(1)

NAME

pstack — print stack traces from Linux processes and core files

SYNOPSIS

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 another 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 usable 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 libraries.

-h, --help

Print a usage summary and exit.

-j, --json

Write stack traces as JSON rather than text. The JSON representation is intended 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 debuginfod 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.

GO GOROUTINE OFFSET DATA

Parked Go goroutine traces require an offset-data file named gooff-<major>.<minor>-<architecture>.json. A file generated with one patch release is used for its Go minor series. The installed data is searched through the current directory and XDG data locations. Use pstack-mkgooff with a Go executable containing DWARF to generate data for its Go runtime. When Go is available at build time, the go-offset-probe build target creates a suitable local executable.

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; alternatively, -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