proc(1) User Commands proc(1)NAME
proc, pflags, pcred, pldd, psig, pstack, pfiles, pwdx, pstop, prun,
pwait, ptime - 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 [-F] [pid | core]...
/usr/bin/psig [-n] pid ...
/usr/bin/pstack [-F] pid | core [/lwp] ...
/usr/bin/pfiles [-Fn] pid...
/usr/bin/pwdx pid...
/usr/bin/pstop pid...
/usr/bin/prun pid...
/usr/bin/pwait [-v] pid...
/usr/bin/ptime command [arg]...
DESCRIPTION
The proc tools are utilities that exercise features of /proc (see
proc(4)). 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(4)).
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 lwp in each process.
pcred Print or set the credentials (effective, real,
saved UIDs 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).
pstack Print a hex+symbolic stack trace for each lwp in
each process.
pfiles Report fstat(2) and fcntl(2) information for all
open files in each process. In addition, a path to
the file is reported if the information is avail‐
able from /proc/pid/path. This is not necessarily
the same name used to open the file. See proc(4)
for more information.
pwdx Print the current working directory of each
process.
pstop Stop each process (PR_REQUESTED stop).
prun Set each process running (inverse of pstop).
pwait Wait for all of the specified processes to termi‐
nate.
ptime Time the command, like time(1), but using
microstate accounting for reproducible precision.
Unlike time(1), children of the command are not
timed.
OPTIONS
The following 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 dis‐
plays 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 only) Verbose. Reports terminations to standard
output.
Additionally, 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 supplemen‐
tary 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 order to set the credentials of another process, a process must have
sufficient privilege to change its user and group ids to those speci‐
fied according to the rules laid out in setuid(2) and it must have suf‐
ficient 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 noth‐
ing 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 con‐
trolling 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 ques‐
tion.
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 informa‐
tion 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
run-time link-editor debugging interface (librtld_db) cannot be able to
initialize. 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(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWesu │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │See below. │
└─────────────────────────────┴─────────────────────────────┘
Human Readable Output is Unstable. Options are Evolving.
SEE ALSOgcore(1), ldd(1), pargs(1), pgrep(1), pkill(1), plimit(1), pmap(1),
preap(1), ps(1), ptree(1), ppgsz(1), pwd(1), rlogin(1), ssh(1),
time(1), truss(1), wait(1), fcntl(2), fstat(2), setuid(2), dlopen(3C),
signal.h(3HEAD), core(4), proc(4), process(4), attributes(5), zones(5)WARNINGS
The following 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. Stopping a heavily used
process in a production environment, even for a short amount of time,
can cause severe bottlenecks and even hangs of these processes, 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 is traced using the above men‐
tioned proc tools. Because of this, stopping a UNIX process in a pro‐
duction environment should be avoided.
A process 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.
SunOS 5.10 1 Mar 2011 proc(1)
