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

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

       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 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 con-
		 nected) 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 nec-
		 essarily 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 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  com-
		 mand 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 process has control.

       -n    (psig  and pfiles only) Sets non-verbose mode. psig displays signal handler addresses rather than names. pfiles does not display ver-
	     bose 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.

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

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWesu			   |
       +-----------------------------+-----------------------------+
       |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),  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, 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.

SunOS 5.11							    10 Dec 2008 							   proc(1)