proc(1)                                                                                                                                    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...]

       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  sys-
       tem.

       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 .

       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 available 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 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.

       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 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.

       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 spec-
                       ified  as  a  comma-separated list of group names ids. An empty list clears the supplementary group list of the target pro-
                       cesses.

       -l login        Sets the real, effective, and saved UIDs of the target processes to the UID of the specified login. Sets the  real,  effec-
                       tive,  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 order 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.

       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  dead-
       lock in this case.

       See .

       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.

       The following exit values are returned:

       0                       Successful operation.

       non-zero                An error has occurred.

       /proc/*                 process files

       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.

       gcore(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), 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)

       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 termi-
       nate abnormally. Thus, for example, a database server under heavy load could hang when one of the database processes is  traced  using  the
       above mentioned proc tools. Because of this, stopping a UNIX process in a production 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.

                                                                    11 Oct 2005                                                            proc(1)