converted man page

[unix-history] / usr / src / bin / ps / ps.1

.\" Copyright (c) 1980, 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)ps.1	6.7 (Berkeley) %G%
.\"
.Dd 
.Dd 
.Dt PS 1
.Os BSD 4
.Sh NAME
.Nm ps
.Nd display current process status
.Sh SYNOPSIS
.Nm ps
.Op Fl acegklnstuvwxU\&\#\&
.Sh DESCRIPTION
.Nm Ps
displays the current process status.
Normally, only your processes are candidates to be printed by
.Nm ps ;
specifying
.Fl a
causes other users' processes to be candidates to be printed;
specifying
.Fl x
includes processes without control terminals in the candidate pool.
While
.Nm ps
is a fairly accurate snapshot of the system,
.Nm Ps
cannot begin and finish a snapshot of the system as fast as some processes
themselves change state.  At times there may be minor discrepancies.
.Pp
All output formats include, for each process, the process id PID,
control terminal of the process TT, cpu time used by the process TIME
(this includes both user and system time), the state STAT of the process,
and an indication of the COMMAND which is running.
The state is given by a sequence of letters, e.g. ``RWNA''.
The first letter indicates the runnability of the process:
R for runnable processes,
T for stopped processes,
P for processes in page wait,
D for those in disk (or other short term) waits,
S for those sleeping for less than about 20 seconds,
and I for idle (sleeping longer than about 20 seconds)
processes.
Additional characters after these, if any,
indicate additional state information.
The letter W indicates that a process is swapped out,
showing W if it is, or a blank if it is loaded (in-core).
A process which has specified a soft limit on memory requirements
and which is exceeding that limit shows >; such a process is (necessarily)
not swapped.
An additional letter may indicate whether a process is running with altered
CPU scheduling priority (nice); if the process priority is reduced,
an N is shown, if the process priority has been artificially raised then
a `<' is shown.
The final optional letter
indicates any special treatment of the process for virtual
memory replacement; the letters correspond to options to the
.Xr vadvise  2
call; currently the possibilities are A standing for VA_ANOM and
S for VA_SEQL.
An A typically represents a
.Xr lisp  1
in garbage collection, and S is typical of large image processing programs
which are using virtual memory to sequentially address voluminous data.
.Pp
Here are the options:
.Tp Fl a
asks for information regarding processes associated with terminals (ordinarily
only one's own processes are displayed).
.Tp Fl c
prints the command name, as stored internally in the system for purposes
of accounting, rather than the command arguments, which are kept
in the process' address space.  This is more reliable, if less informative,
since the process is free to destroy the latter information.
.Tp Fl e
Asks for the environment to be printed as well as the arguments to the command.
.Tp Fl g
Asks for all processes.
Without this option,
.Nm ps
only prints ``interesting'' processes.
Processes are deemed to be uninteresting if they are process group leaders.
This normally eliminates top-level command interpreters and processes
waiting for users to login on free terminals.
.Tp Fl k
causes the file
.Pa /vmcore
to be used instead of
.Pa /dev/kmem
and
.Ar /dev/mem
for non-interactive (after the fact)
debugging.
.Tp Fl l
asks for a detailed list, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and
WCHAN as described below.
.Tp Fl n
Asks for numerical output.
In a long listing, the WCHAN field is printed numerically rather than
symbolically, or, in a user listing, the USER field is replaced by a
UID field.
.Tp Fl s
Adds the size SSIZ of the kernel stack of each process (for use by system
maintainers) to the basic output format.
.Ct Fl t
.Ar x
.Cx
Only output information on processes whose controlling tty is
.Ar x
(which should be specified as printed by
.Nm ps ,
e.g.
.Ar t3
for tty3,
.Ar tco
for console,
.Ar td0
for ttyd0,
.Ar t ?
for processes with no tty,
.Ar t
for processes at the current tty,
etc).
This option must be the last one given.
.Tp Fl u
A user oriented output is produced.
This includes fields USER, %CPU, NICE, SIZE, and RSS as described below.
.Tp Fl v
A version of the output containing virtual memory statistics is output.
This includes fields RE, SL, PAGEIN, SIZE, RSS, LIM, TSIZ, TRS, %CPU
and %MEM, described below.
.Tp Fl w
Use a wide output format (132 columns rather than 80); if repeated,
e.g. ww, use arbitrarily wide output.
This information is used to decide how much of long commands to print.
.Tp Fl x
asks even about processes with no terminal.
.Tp Fl U
causes ps to update a private database where it keeps system
information.  Thus ``ps U'' should be included in the
.Pa /etc/rc
file.
.Tp Fl #
A process number may be given,
(indicated here by #),
in which case the output
is restricted to that process.
This option must also be last.
.Tp
.Pp
A second argument is taken
to be the file containing the system's
namelist.  Otherwise, /vmunix is used.
A third argument tells
.Nm ps
where to look for
.Pa core
if the
.Fl k
option is given, instead of
.Pa /vmcore .
If a fourth argument is given, it
is taken to be the name of a swap file to use instead of
the default
.Pa /dev/drum .
.Pp
Fields which are not common to all output formats:
.Pp
.Dw PAGEIN
.Dp Li USER
name of the owner of the process
.Dp Li %CPU
cpu utilization of the process; this is a decaying average over up to
a minute of previous (real) time.  Since the time base over which this
is computed varies (since processes may be very young) it is possible
for the sum of all %CPU fields to exceed 100%.
.Dp Li NICE
(or NI) process scheduling increment (see
.Xr setpriority  2  )
.Dp Li SIZE
virtual size of the process (in 1024 byte units)
.Dp Li RSS
real memory (resident set) size of the process (in 1024 byte units)
.Dp Li LIM
soft limit on memory used, specified via a call to
.Xr setrlimit  2  ;
if no limit has been specified then shown as
.Ar xx
.Dp Li TSIZ
size of text (shared program) image
.Dp Li TRS
size of resident (real memory) set of text
.Dp Li %MEM
percentage of real memory used by this process.
.Dp Li RE
residency time of the process (seconds in core)
.Dp Li SL
sleep time of the process (seconds blocked)
.Dp Li PAGEIN
number of disk i/o's resulting from references by the process
to pages not loaded in core.
.Dp Li UID
process owner's user-id (numerical)
.Dp Li PPID
parent process id (numerical)
.Dp Li CP
short-term cpu utilization factor (used in scheduling)
.Dp Li PRI
process priority (non-positive when in non-interruptible wait)
.Dp Li ADDR
swap address of the process
.Dp Li WCHAN
address of event on which a process is waiting (an address in the system).
A symbol is chosen that classifies the address, unless numerical
output is requested (see the
.Fl n
flag).
In this case, the initial part of the address is
trimmed off and is printed hexadecimally, e.g., 0x80004000 prints as 4000.
.Pp
.Dp Li F
flags associated with process as in
.Aq Pa sys/proc.h :
.Pp
.Cw SDETACH 080000
.Cl SLOAD	000001	in core
.Cl SSYS	000002	swapper or pager process
.Cl SLOCK	000004	swapping out process
.Cl SSWAP	000008	save area flag
.Cl STRC	000010	tracing the process
.Cl SWTED	000020	trace flag
.Cl SULOCK	000040	user settable lock in core
.Cl SPAGE	000080	process in page wait state
.Cl SKEEP	000100	another flag to prevent swap out
.Cl SDLYU	000200	delayed unlock of pages
.Cl SWEXIT	000400	working on exiting
.Cl SPHYSIO	000800	doing physical i/o (bio.c)
.Cl SVFORK	001000	process resulted from vfork()
.Cl SVFDONE	002000	another vfork flag
.Cl SNOVM	004000	no vm, parent in a vfork()
.Cl SPAGI	008000	init data space on demand from inode
.Cl SANOM	010000	system detected anomalous vm behavior
.Cl SUANOM	020000	user warned of anomalous vm behavior
.Cl STIMO	040000	timing out during sleep
.Cl SDETACH	080000	detached inherited by init
.Cl SOUSIG	100000	using old signal mechanism
.Cw
.Dp
.Pp
.Tp Aq Li defunct
A
.Aq defunct
process is one that has exited, but whose parent process has
not waited for it.
A process that has exited and has a parent that has not
yet waited for the process is marked
.Aq Li defunct .
.Tp Aq Li exiting
A process
which is blocked trying to exit is marked
.Aq Li exiting
.Tp
.Pp
.Nm Ps
makes an educated guess as to the file name
and arguments given when the process was created
by examining memory or the swap area.
The method is inherently somewhat unreliable and in any event
a process is entitled to destroy this information,
so the names cannot be counted on too much.
.Sh FILES
.Dw /etc/pasdatabase
.Di L
.Dp Pa /vmunix
system namelist
.Dp Pa /dev/kmem
kernel memory
.Dp Pa /dev/drum
swap device
.Dp Pa /vmcore
core file
.Dp Pa /dev
searched to find swap device and tty names
.\" .Dp Pa /etc/psdatabase
.\" system namelist, device, and wait channel information
.Dp
.Sh SEE ALSO
.Xr kill 1 ,
.Xr w 1
.Sh HISTORY
A
.Nm Ps
command appeared in VERSION 6 AT&T UNIX.