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 [-Fl] [pid | core]...


/usr/bin/psig [-n] pid...


/usr/bin/pstack [-F] pid | core [/lwp] ...


/usr/bin/pfiles [-Fn] pid | core...


/usr/bin/pwdx [-m] [-q | -v] pid | core...


/usr/bin/pstop pid[/lwp] ...


/usr/bin/prun pid[/lwp] ...


/usr/bin/pwait [-v] pid...


/usr/bin/ptime [-Fm] -p pidlist


/usr/bin/ptime [-m] 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. If an lwp has a
non-empty signal mask, it will be printed.


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). Use pflags to see more information about
currently pending signals and signal masks.


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 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 pidlist version is used, display a snapshot of
timing statistics for the specified processes. The pidlist
may have a single process or be a comma or space delineated
list. If a space delineated list is used, callers will need
to ensure that it is properly quoted or escaped for their
shell.

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 pwdx only) Verbose. For pwait Reports terminations
to standard output. For pwdx reports all information about the
current working directory, mount point, and the corresponding
file system.


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.


In addition to the general options, pwdx supports the following
options:

-m
Instead of showing the process's current working
directory, show the mount point of the file system
that the current working directory is a part of.


-q
Only the requested path (either the current working
directory or the mount point path). Do not print the
process ID or core file information.


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 from another system
using rlogin(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 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(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See below. |
+--------------------+-----------------+


The human readable output is Uncommitted. The options are Committed.

SEE ALSO

gcore(1), ldd(1), pargs(1), pauxv(1), penv(1), pgrep(1), pkill(1),
plimit(1), pmap(1), ppgsz(1), preap(1), ps(1), ptree(1), pwd(1),
rlogin(1), time(1), truss(1), wait(1), fcntl(2), fstat(2), setuid(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.


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.

June 15, 2016 PROC(1)