pstack(1)
Name
proc, ptools, pflags, pcred, pldd, psig, pstack, pfiles, pwdx, pstop, prun, pwait, ptime, phang - proc tools
Synopsis
/usr/bin/pflags [-r]
pid | core [/lwp] ...
/usr/bin/pcred [pid |
core]...
/usr/bin/pcred [-u user/uid
] [-g group/gid] [
-G grouplist] pid...
/usr/bin/pcred -l login
pid...
/usr/bin/pldd [-Fl] [
pid | core]...
/usr/bin/psig [-n] pid | core [/lwp] ...
/usr/bin/pstack [-F] [-D options]
pid | core [/lwp] ...
/usr/bin/pfiles [-n] [pid | core]...
/usr/bin/pwdx pid...
/usr/bin/pstop pid[/
lwp] ...
/usr/bin/prun pid[/
lwp] ...
/usr/bin/pwait [-v]
pid...
/usr/bin/ptime [-Fm] [-p
] pid...
/usr/bin/ptime [-m]command
[arg]...
/usr/bin/phang [-v]
command [arg ...]
Description
The proc tools are utilities that exercise features of /proc (see proc(5)). Most of them take a list
of process-ids (pid). The tools that do take process-ids
also accept /proc/nnn as a process-id,
so the shell expansion /proc/* can be used to specify all
processes in the system.
Some of the proc tools can also be applied to core files (see core(5)). The tools that apply to
core files accept a list of either process IDs or names
of core files or both.
Some of the proc tools can operate on individual
threads. Users can examine only selected threads by appending /thread-id
to the process-id or core. Multiple threads can be selected
using the - and , delimiters. For example
/1,2,7-9 examines threads 1, 2,
7, 8, and 9.
See WARNINGS.
- pflags
Print the /proc tracing flags, the pending
and held signals, and other /proc status information for
each process or specified lwps in each process.
- pcred
Print or set the credentials (effective, real, saved UID
s and GIDs) of each process.
- pldd
List the dynamic libraries linked into each process, including
shared objects explicitly attached using dlopen(3C). See also ldd(1).
- psig
List the signal actions and handlers of each process. See signal.h(3HEAD). A signal is reported as "blocked", if it is masked by all of the
specified LWPs. If there is no LWP specification, this means all LWPs in the
process/core.
- pstack
Print a stack trace for each process or specified LWPs in each process. Each frame is
described by an address and a symbol/offset pair; if the underlying load object contains
suitable DWARF (which requires compilation with "–g" option) then the
corresponding source code file name and line number are also displayed.
In addition to the general options, pstack supports the following
options:
- –D
-
Specify DWARF related sub-options. The supported sub-options are:
- absolutepaths
-
Display source code file names by using absolute paths.
- frames=n
-
Annotate only the first n frames.
- pfiles
Report fstat(2) and fcntl(2) information for all open files in each process. For network
endpoints, the local (and peer if connected) address information is also provided. For
sockets, the socket type, socket options and send and receive buffer sizes are also provided.
In addition, a path to the file is reported if the information is available from
/proc/pid/path. This is not necessarily the same name used to open the
file. See proc(5) for more information.
- pwdx
Print the current working directory of each process.
- pstop
Stop each process or the specified lwps (PR_REQUESTED stop).
- prun
Set running each process or the specified lwps (the inverse
of pstop).
- pwait
Wait for all of the specified processes to terminate.
- ptime
Time the command, like time(1), but using microstate accounting
for reproducible precision. Unlike time(1),
children of the command are not timed.
If the –p pid version is
used, display a snapshot of timing statistics for the specified pid.
- phang
Execute a command, but stops it before it has executed its
first user-level instruction, in preparation for attachment by a debugger.
Options
The following general options are supported:
- –F
Force. Grabs the target process even if another process has control.
- –n
(psig and pfiles only)
Sets non-verbose mode. psig displays signal handler addresses
rather than names. pfiles does not display verbose information
for each file descriptor. Instead, pfiles limits its output
to the information that would be retrieved if the process applied fstat(2) to each of its file descriptors.
- –r
(pflags only) If the process is stopped,
displays its machine registers.
- –v
(pwait and phang only)
Sets verbose mode.
- pwait
Reports terminations to standard output.
- phang
Prints the new process-id on standard output.
- –?
- –-help
Print usage message and immediately exit.
In addition to the general options, pcred supports
the following options:
- –g group/gid
Sets the real, effective, and saved group ids (GIDs)
of the target processes to the specified value.
- –G grouplist
Sets the supplementary GIDs of the target
process to the specified list of groups. The supplementary groups should be
specified as a comma-separated list of group names ids. An empty list clears
the supplementary group list of the target processes.
- –l login
Sets the real, effective, and saved UIDs
of the target processes to the UID of the specified login.
Sets the real, effective, and saved GIDs of the target
processes to the GID of the specified login. Sets the supplementary
group list to the supplementary groups list of the specified login.
- –u user/uid
Sets the real, effective, and saved user ids (UIDs)
of the target processes to the specified value.
In addition to the general options, pldd supports
the following option:
- –l
Shows unresolved dynamic linker map names.
In addition to the general options, ptime supports
the following options:
- –m
Display the full set of microstate accounting statistics.
The displayed fields are as follows:
- real
Wall clock time.
- user
User level CPU time.
- sys
System call CPU time.
- trap
Other system trap CPU time.
- tflt
Text page fault sleep time.
- dflt
Data page fault sleep time.
- kflt
Kernel page fault sleep time.
- lock
User lock wait sleep time.
- slp
All other sleep time.
- lat
CPU latency (wait) time.
- stop
Stopped time.
- –p pid
Displays a snapshot of timing statistics for the specified
pid.
To set the credentials of another process, a process must have sufficient
privilege to change its user and group ids to those specified according to
the rules laid out in setuid(2) and
it must have sufficient privilege to control the target process.
Usage
These proc tools stop their target processes while inspecting them and
reporting the results: pfiles, pldd,
and pstack. A process can do nothing while it is stopped.
Thus, for example, if the X server is inspected by one of these proc tools
running in a window under the X server's control, the whole window system
can become deadlocked because the proc tool would be attempting
to print its results to a window that cannot be refreshed. Logging in from
another system using ssh(1) and
killing the offending proc tool would clear up the deadlock
in this case.
See WARNINGS.
Caution should be exercised when using the –F flag.
Imposing two controlling processes on one victim process can lead to chaos.
Safety is assured only if the primary controlling process, typically a debugger,
has stopped the victim process and the primary controlling process is doing
nothing at the moment of application of the proc tool in
question.
Some of the proc tools can also be applied to core files, as shown by
the synopsis above. A core file is a snapshot of a process's state and is
produced by the kernel prior to terminating a process with a signal or by
the gcore(1) utility. Some
of the proc tools can need to derive the name of the executable corresponding
to the process which dumped core or the names of shared libraries associated
with the process. These files are needed, for example, to provide symbol table
information for pstack(1).
If the proc tool in question is unable to locate the needed executable or
shared library, some symbol information is unavailable for display. Similarly,
if a core file from one operating system release is examined on a different
operating system release, the runtime link-editor debugging interface
(librtld_db) cannot be initialized. In this case, symbol
information for shared libraries is not available.
Exit Status
The following exit values are returned:
- 0
Successful operation.
- non-zero
An error has occurred.
Files
- /proc/*
process files
Attributes
See attributes(7) for
descriptions of the following attributes:
|
|
Availability |
system/core-os |
Interface Stability |
See below. |
|
The human readable output is Uncommitted. The options are Committed.
See Also
gcore(1),
ldd(1),
pargs(1),
pgrep(1),
pkill(1),
plimit(1),
pmap(1),
ppgsz(1),
preap(1),
ps(1),
ptree(1),
pwd(1),
rlogin(1),
ssh(1),
time(1),
truss(1),
wait(1),
fcntl(2),
fstat(2),
setuid(2),
sigprocmask(2),
dlopen(3C),
signal.h(3HEAD),
core(5),
proc(5),
process(5),
attributes(7),
zones(7)
Warnings
The following proc tools stop their target processes
while inspecting them and reporting the results: pfiles,
pldd, and pstack. However, even if pstack operates
on an individual thread, it stops the whole process. The whole purpose of
phang is to stop the created process. This is only useful as a prelude
to attaching to the process from a debugger running elsewhere.
A process or thread can do nothing while it is stopped. Stopping a heavily
used process or thread in a production environment, even for a short amount
of time, can cause severe bottlenecks and even hangs of these processes or
threads, causing them to be unavailable to users. Some databases could also
terminate abnormally. Thus, for example, a database server under heavy load
could hang when one of the database processes or threads is traced using the
above mentioned proc tools. Because of this, stopping a
UNIX process or thread in a production environment should be avoided.
A process or thread being stopped by these tools can be identified by
issuing /usr/bin/ps –eflL and looking for “
T” in the first column. Notice that certain processes, for
example “sched”, can show the “T”
status by default most of the time.
The process ID returned for locked files on network file systems might
not be meaningful.