unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

proc(1)                          User Commands                         proc(1)



NAME
       proc,  pflags,  pcred,  pldd,  psig, pstack, pfiles, pwdx, pstop, prun,
       pwait, ptree, 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/ptree [-a] [-c] [-z zone] [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.

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



       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.



       -c       (ptree only). Contracts. Show process contract memberships  in
                addition   to   parent-child  relationships.  See  process(4).
                Implies -a.



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



       -z zone  (ptree only) Prints only processes in the specified zone. Each
                zone ID can be specified as either a zone name or a  numerical
                zone  ID.   This  option  is  only useful when executed in the
                global zone.



       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 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  supplemen-
                       tary 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  speci-
       fied according to the rules laid out in setuid(2) and it must have suf-
       ficient 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 noth-
       ing 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 WARNINGS.

       Caution should be exercised when using the -F flag. Imposing  two  con-
       trolling  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  ques-
       tion.

       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 informa-
       tion 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(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).    ATTRIBUTE   TYPEATTRIBUTE  VALUE  AvailabilitySUNWesu
       Interface StabilitySee below.


       Human Readable Output is Unstable. Options are Evolving.

SEE ALSO
       gcore(1), ldd(1), pargs(1),  pgrep(1),  pkill(1),  plimit(1),  pmap(1),
       preap(1),   ps(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)

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 men-
       tioned proc tools. Because of this, stopping a UNIX process in  a  pro-
       duction 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.



SunOS 5.10                        28 Oct 2004                          proc(1)