pstack

pstack [PID]

PID
    The process ID of the target process for which to display the stack trace. This is the only required argument.

The `pstack` command is a utility used to display the stack trace of a running process. It attaches to the specified process and outputs the current call stack for each of its threads. This is particularly useful for debugging hung applications, identifying where a process is spending its time, or understanding its current execution path. Internally, `pstack` is often a simple wrapper script that invokes the GNU Debugger (gdb) with specific commands (e.g., `thread apply all bt`) to achieve its functionality. Because it uses `gdb`, it requires appropriate permissions to attach to the target process. The output includes function names and often line numbers if the executable was compiled with debugging symbols. It provides a quick, non-interactive way to inspect process state.

Permissions: Requires `ptrace` permissions, typically meaning it must be run as the root user or the same user that owns the target process. System security settings like `/proc/sys/kernel/yama/ptrace_scope` can restrict its usage.
Process Interruption: Attaching to a process temporarily pauses it while stack information is gathered. This pause is usually very brief but can affect real-time or performance-sensitive applications.
Symbol Information: The detail of the stack trace (function names, line numbers) depends on whether the executable was compiled with debugging symbols. Without symbols, only addresses might be shown.
Wrapper Script: `pstack` is often a shell script wrapper around `gdb`. For advanced debugging, using `gdb` directly offers more control.

pstack typically works by spawning a `gdb` process, instructing it to attach to the specified PID, execute the `thread apply all bt` command (which prints a backtrace for all threads), and then detach. This makes it a quick, non-interactive way to get stack information.

The `/proc/sys/kernel/yama/ptrace_scope` sysctl parameter controls who can use `ptrace` (and thus `pstack`) on processes. A value of `0` typically means any user can attach to any process they own. A value of `1` (default on many systems) means only a parent process can trace its children, or a process can only trace another if it has CAP_SYS_PTRACE capability (e.g., root).

The `pstack` command has historically served as a convenient wrapper for obtaining stack traces without needing to interact directly with the `gdb` debugger. It emerged as a simple utility to quickly inspect running processes. Over time, as users became more familiar with `gdb` and its direct attachment capabilities, `pstack`'s role has sometimes been described as a compatibility or legacy script, though it remains widely used for quick diagnostic checks due to its simplicity.

gdb(1), strace(1), ltrace(1), top(1), ps(1)