prun(1)

NAME

     proc, pflags,  pcred,  pldd,  psig,  pstack,  pfiles,  pwdx,
     pstop, prun, pwait, ptree, ptime - proc tools

SYNOPSIS

     /usr/bin/pflags [-r] [pid | core] ...

     /usr/bin/pcred [pid | core] ...

     /usr/bin/pldd [-F] [pid | core] ...

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

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

     /usr/bin/pfiles [-F] pid...

     /usr/bin/pwdx [-F] pid...

     /usr/bin/pstop pid...

     /usr/bin/prun pid...

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

     /usr/bin/ptree [-a] [pid | user] ...

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

     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 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(3DL). See also ldd(1).

     psig  List the signal actions and handlers of each  process.
           See signal(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.

     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.

     ptree Print the process trees containing the specified  pids
           or  users,  with  child  processes indented from their
           respective parent processes. An argument of all digits
           is  taken  to be a process-id, otherwise it is assumed
           to be a user login name. Default is all processes.

     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:

     -a    (ptree only) All. Includes children of process 0.

     -F    Force. Grabs the target process even if  another  pro-
           cess has control.

     -n    (psig only) Displays signal handler  addresses  rather
           than names.

     -r    (pflags only) If the process is stopped, displays  its
           machine registers.

     -v    (pwait only) Verbose. Reports terminations to standard
           output.

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.

     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 may 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 will  be  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) may
     not be able to initialize. In this case, symbol  information
     for shared libraries will not be available.

EXIT STATUS

     The following exit values are returned:

     0     Successful operation.

     non-zero
           An error has occurred.

FILES

     /proc/*
           process files

     /usr/proc/lib/*
           proc tools supporting files

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:
     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWesu (32-bit)            |
    |_____________________________|_____________________________|
    |                             | SUNWesxu (64-bit)           |
    |_____________________________|_____________________________|

SEE ALSO

     gcore(1), ldd(1), pargs(1), pgrep(1),  pkill(1),  plimit(1),
     pmap(1),   preap(1),   ps(1),  pwd(1),  rlogin(1),  time(1),
     truss(1),   wait(1),   fcntl(2),   fstat(2),    dlopen(3DL),
     signal(3HEAD), core(4), proc(4), attributes(5)

WARNINGS

     The following proc tools stop their target  processes  while
     inspecting   them  and  reporting the results: pfiles, pldd,
     pmap, 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
     mentioned  proc tools. Because of this, stopping a UNIX pro-
     cess 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.