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 [-Fl] [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[/lwp] ...
/usr/bin/prun pid[/lwp] ...
/usr/bin/pwait [-v] pid...
/usr/bin/ptime [-Fm] [-p] pid...
/usr/bin/ptime [-m]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/*
SunOS 5.11 Last change: 10 Dec 2008 1
User Commands proc(1)
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 process or specified lwps in each pro-
cess.
pcred Print or set the credentials (effective, real,
saved UIDs and GIDs) of each process.
pldd List the dynamic libraries linked into each pro-
cess, including shared objects explicitly attached
using dlopen(3C). See also ldd(1).
psig List the signal actions and handlers of each pro-
cess. See signal.h(3HEAD).
pstack Print a hex]symbolic stack trace for each process
or specified lwps in each process.
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 informa-
tion 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 avail-
able from /proc/pid/path. This is not necessarily
the same name used to open the file. See proc(4)
for more information.
SunOS 5.11 Last change: 10 Dec 2008 2
User Commands proc(1)
pwdx Print the current working directory of each pro-
cess.
pstop Stop each process or the specified lwps
(PREQUESTED stop).
prun Set running each process or the specified lwps
(the inverse of pstop).
pwait Wait for all of the specified processes to ter-
minate.
ptime Time the command, like time(1), but using micro-
state 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.
OPTIONS
The following general options are supported:
-F Force. Grabs the target process even if another pro-
cess 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 only) Verbose. Reports terminations to standard
output.
In addition to the general options, pcred supports the fol-
lowing options:
SunOS 5.11 Last change: 10 Dec 2008 3
User Commands proc(1)
-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 speci-
fied value.
In addition to the general options, pldd supports the fol-
lowing option:
-l Shows unresolved dynamic linker map names.
In addition to the general options, ptime supports the fol-
lowing 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.
SunOS 5.11 Last change: 10 Dec 2008 4
User Commands proc(1)
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 inspect-
ing 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 win-
dow that cannot be refreshed. Logging in from from another
system using rlogin(1) and killing the offending proc tool
would clear up the deadlock in this case.
See WARNINGS.
SunOS 5.11 Last change: 10 Dec 2008 5
User Commands proc(1)
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 pro-
cess 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 ter-
minating 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. Simi-
larly, if a core file from one operating system release is
examined on a different operating system release, the run-
time link-editor debugging interface (librtlddb) 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
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 10 Dec 2008 6
User Commands proc(1)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWesu
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), preap(1), ps(1), ptree(1), ppgsz(1), pwd(1), rlo-
gin(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. However, even if pstack operates on an individual
thread, it stops the whole process.
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 data-
bases 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 men-
tioned 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.
SunOS 5.11 Last change: 10 Dec 2008 7
|
