Reformatting page.  Please Wait... done


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


Illumos             Last change: Oct 23, 2012                   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


Illumos             Last change: Oct 23, 2012                   2


User Commands                                             PROC(1)


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


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


Illumos             Last change: Oct 23, 2012                   3


User Commands                                             PROC(1)


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

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


Illumos             Last change: Oct 23, 2012                   4


User Commands                                             PROC(1)


     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.


               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.


Illumos             Last change: Oct 23, 2012                   5


User Commands                                             PROC(1)


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


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


Illumos             Last change: Oct 23, 2012                   6


User Commands                                             PROC(1)


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  attri-
     butes:


     _______________________________________
    |   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)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


Illumos             Last change: Oct 23, 2012                   7


User Commands                                             PROC(1)


     databases  could  also terminate abnormally. Thus, for exam-
     ple, 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.


Illumos             Last change: Oct 23, 2012                   8