overhaul the keywords section;

1 files changed, 245 insertions, 241 deletions

diff --git a/bin/ps/ps.1 b/bin/ps/ps.1
index 0eacddcd2de..3c6e0d4574c 100644
--- a/bin/ps/ps.1
+++ b/bin/ps/ps.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ps.1,v 1.61 2006/11/01 21:40:17 jmc Exp $
+.\"	$OpenBSD: ps.1,v 1.62 2006/11/02 12:34:19 jmc Exp $
 .\"	$NetBSD: ps.1,v 1.16 1996/03/21 01:36:28 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
@@ -107,14 +107,12 @@ and command.
 Extract values associated with the name list from the specified core
 instead of the running kernel.
 .It Fl m
-Sort by memory usage, instead of by start time
-.Tn ID .
+Sort by memory usage, instead of by start time ID.
 .It Fl N Ar system
 Extract the name list from the specified system instead of the running kernel.
 .It Fl O Ar fmt
 Add the information associated with the space or comma separated list
-of keywords specified, after the process
-.Tn ID ,
+of keywords specified, after the process ID,
 in the default information
 display.
 Keywords may be appended with an equals sign
@@ -131,11 +129,9 @@ and a string.
 This causes the printed header to use the specified string instead of
 the standard header.
 .It Fl p Ar pid
-Display information associated with the specified process
-.Tn ID .
+Display information associated with the specified process ID.
 .It Fl r
-Sort by current CPU usage, instead of by start time
-.Tn ID .
+Sort by current CPU usage, instead of by start time ID.
 .It Fl S
 Change the way the process time is calculated by summing all exited
 children to their parent process.
@@ -182,68 +178,193 @@ Display information about processes without controlling terminals.
 .El
 .Pp
 .Ex -std ps
-.Pp
-All available keywords are listed below.
-Some of these keywords are further specified as follows:
-.Bl -tag -width indent
-.It %cpu
+.Sh KEYWORDS
+The following is a complete list of the available keywords
+and their meanings.
+Several of them have aliases,
+which are also noted.
+.Bl -tag -width "sigignoreXX" -offset 3n
+.It Cm %cpu
+Alias:
+.Cm pcpu .
 The 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
-.Tn \&%cpu
+.Cm %cpu
 fields to exceed 100%.
-.It %mem
+.It Cm %mem
+Alias:
+.Cm pmem .
 The percentage of real memory used by this process.
-.It flags
+.It Cm acflag
+Alias:
+.Cm acflg .
+Accounting flag.
+.It Cm command
+Alias:
+.Cm args .
+Command and arguments.
+.It Cm cpu
+Short-term CPU usage factor (for scheduling).
+.It Cm cpuid
+CPU ID (zero on single processor systems).
+.It Cm dsiz
+Data size, in Kilobytes.
+.It Cm emul
+Name of system call emulation environment.
+.It Cm flags
+Alias:
+.Cm f .
 The flags (in hexadecimal) associated with the process as in
 the include file
 .Aq Pa sys/proc.h :
-.Bl -column P_NOCLDSTOP P_NOCLDSTOP
-.It Dv "P_ADVLOCK" Ta No "0x0000001	process may hold a POSIX advisory lock"
-.It Dv "P_CONTROLT" Ta No "0x0000002	process has a controlling terminal"
-.It Dv "P_INMEM" Ta No "0x0000004	process is loaded into memory"
-.It Dv "P_NOCLDSTOP" Ta No "0x0000008	no
-.Dv SIGCHLD
-when children stop
-.It Dv "P_PPWAIT" Ta No "0x0000010	parent is waiting for child to exec/exit"
-.It Dv "P_PROFIL" Ta No "0x0000020	process has started profiling"
-.It Dv "P_SELECT" Ta No "0x0000040	selecting; wakeup/waiting danger"
-.It Dv "P_SINTR" Ta No "0x0000080	sleep is interruptible"
-.It Dv "P_SUGID" Ta No "0x0000100	process had set id privileges since last exec"
-.It Dv "P_SYSTEM" Ta No "0x0000200	system process: no sigs, stats or swapping"
-.It Dv "P_TIMEOUT" Ta No "0x0000400	timing out during sleep"
-.It Dv "P_TRACED" Ta No "0x0000800	process is being traced"
-.It Dv "P_WAITED" Ta No "0x0001000	debugging process has waited for child"
-.It Dv "P_WEXIT" Ta No "0x0002000	working on exiting"
-.It Dv "P_EXEC" Ta No "0x0004000	process called"
-.Xr exec 3
-.It Dv "P_OWEUPC" Ta No "0x0008000	owe process an addupc() call at next ast"
+.Bd -literal
+P_ADVLOCK 0x0000001  process may hold a POSIX advisory lock
+P_CONTROLT 0x0000002  process has a controlling terminal
+P_INMEM 0x0000004     process is loaded into memory
+P_NOCLDSTOP 0x0000008 no SIGCHLD when children stop
+P_PPWAIT 0x0000010    parent is waiting for child to
+		      exec/exit
+P_PROFIL 0x0000020    process has started profiling
+P_SELECT 0x0000040    selecting; wakeup/waiting danger
+P_SINTR 0x0000080     sleep is interruptible
+P_SUGID 0x0000100     process had set ID privileges since
+		      last exec
+P_SYSTEM 0x0000200    system process: no sigs, stats, or
+		      swapping
+P_TIMEOUT 0x0000400   timing out during sleep
+P_TRACED 0x0000800    process is being traced
+P_WAITED 0x0001000   debugging process has waited for child
+P_WEXIT 0x0002000     working on exiting
+P_EXEC 0x0004000      process called exec(3)
+P_OWEUPC 0x0008000    owe process an addupc() call at next
+		      ast
 .\" the routine addupc is not documented in the man pages
-.It Dv "P_FSTRACE" Ta No "0x0010000	tracing via file system"
-.It Dv "P_SSTEP" Ta No "0x0020000	process needs single-step fixup"
-.It Dv "P_SUGIDEXEC" Ta No "0x0040000	last
-.Xr exec 3
-was set[ug]id
-.It Dv "P_NOCLDWAIT" Ta No "0x0080000	let pid 1 wait for my children"
-.It Dv "P_NOZOMBIE" Ta No "0x0100000	pid 1 waits for me instead of dad"
-.It Dv "P_INEXEC" Ta No "0x0200000	process is doing an exec right now"
-.It Dv "P_SYSTRACE" Ta No "0x0400000	process system call tracing is active"
-.El
-.It lim
+P_FSTRACE 0x0010000   tracing via file system
+P_SSTEP 0x0020000     process needs single-step fixup
+P_SUGIDEXEC 0x0040000 last exec(3) was set[ug]id
+P_NOCLDWAIT 0x0080000 let pid 1 wait for my children
+P_NOZOMBIE 0x0100000  pid 1 waits for me instead of dad
+P_INEXEC 0x0200000    process is doing an exec right now
+P_SYSTRACE 0x0400000  process system call tracing is active
+.Ed
+.It Cm gid
+Effective group.
+.It Cm group
+Text name of effective group ID.
+.It Cm holdcnt
+Number of holds on the process (if non-zero, process can't be swapped).
+.It Cm inblk
+Alias:
+.Cm inblock .
+Total blocks read.
+.It Cm jobc
+Job control count.
+.It Cm ktrace
+Tracing flags.
+.It Cm ktracep
+Tracing vnode.
+.It Cm lim
 The soft limit on memory used, specified via a call to
 .Xr setrlimit 2 .
-.It lstart
+.It Cm logname
+Alias:
+.Cm login .
+Login name of user who started the process.
+.It Cm lstart
 The exact time the command started, using the
 .Dq %c
 format described in
 .Xr strftime 3 .
-.It nice
+.It Cm majflt
+Total page faults.
+.It Cm minflt
+Total page reclaims.
+.It Cm msgrcv
+Total messages received (reads from pipes/sockets).
+.It Cm msgsnd
+Total messages sent (writes on pipes/sockets).
+.It Cm nice
+Alias:
+.Cm ni .
 The process scheduling increment (see
 .Xr setpriority 2 ) .
-.It rss
+.It Cm nivcsw
+Total involuntary context switches.
+.It Cm nsigs
+Alias:
+.Cm nsignals .
+Total signals taken.
+.It Cm nswap
+Total swaps in/out.
+.It Cm nvcsw
+Total voluntary context switches.
+.It Cm nwchan
+Wait channel (as an address).
+.It Cm oublk
+Alias:
+.Cm oublock .
+Total blocks written.
+.It Cm p_ru
+Resource usage (valid only for zombie processes).
+.It Cm paddr
+Swap address.
+.It Cm pagein
+Pageins (same as
+.Cm majflt ) .
+.It Cm pgid
+Process group number.
+.It Cm pid
+Process ID.
+.It Cm ppid
+Parent process ID.
+.It Cm pri
+Scheduling priority.
+.It Cm re
+Core residency time (in seconds; 127 = infinity).
+.It Cm rgid
+Real group ID.
+.It Cm rgroup
+Text name of real group ID.
+.It Cm rlink
+Reverse link on run queue, or 0.
+.It Cm rss
 The real memory (resident set) size of the process (in 1024 byte units).
-.It start
+.It Cm rsz
+Alias:
+.Cm rssize .
+Resident set size + (text size / text use count).
+.It Cm ruid
+Real user ID.
+.It Cm ruser
+User name (from
+.Cm ruid ) .
+.It Cm sess
+Session pointer.
+.It Cm sig
+Alias:
+.Cm pending .
+Pending signals.
+.It Cm sigcatch
+Alias:
+.Cm caught .
+Caught signals.
+.It Cm sigignore
+Alias:
+.Cm ignored .
+Ignored signals.
+.It Cm sigmask
+Alias:
+.Cm blocked .
+Blocked signals.
+.It Cm sl
+Sleep time (in seconds; 127 = infinity).
+.It Cm ssiz
+Stack size, in Kilobytes.
+.It Cm start
+Alias:
+.Cm etime .
 The time the command started.
 If the command started less than 24 hours ago, the start time is
 displayed using the
@@ -257,9 +378,11 @@ format.
 Otherwise, the start time is displayed using the
 .Dq %e%b%y
 format.
-.It state
+.It Cm state
+Alias:
+.Cm stat .
 The state is given by a sequence of letters, for example,
-.Dq Tn RWN .
+.Dq RWN .
 The first letter indicates the run state of the process:
 .Pp
 .Bl -tag -width indent -compact
@@ -285,9 +408,9 @@ information:
 .It +
 The process is in the foreground process group of its control terminal.
 .It \*(Lt
-The process has raised
-.Tn CPU
-scheduling priority.
+The process has a raised CPU
+scheduling priority (see
+.Xr setpriority 2 ) .
 .It \*(Gt
 The process has specified a soft limit on memory requirements and is
 currently exceeding that limit; such a process is (necessarily) not
@@ -305,16 +428,12 @@ The process is trying to exit.
 .It K
 The process is a kernel thread.
 .It L
-The process has pages locked in core (for example, for raw
-.Tn I/O ) .
+The process has pages locked in core (for example, for raw I/O).
 .It N
-The process has reduced
-.Tn CPU
-scheduling priority (see
-.Xr setpriority 2 ) .
+The process has a reduced CPU
+scheduling priority.
 .\" .It S
-.\" The process has asked for
-.\" .Tn FIFO
+.\" The process has asked for FIFO
 .\" page replacement
 .\" .Pf ( Dv MADV_SEQUENTIAL ,
 .\" from
@@ -337,7 +456,25 @@ The process is being monitored by
 On multiprocessor machines, specifies processor number
 .Ar n .
 .El
-.It tt
+.It Cm svgid
+Saved GID from a setgid executable.
+.It Cm svuid
+Saved UID from a setuid executable.
+.It Cm tdev
+Control terminal device number.
+.It Cm time
+Alias:
+.Cm cputime .
+Accumulated CPU time, user + system.
+.It Cm tpgid
+Control terminal process group ID.
+.\".It trss
+.\"Text resident set size, in Kilobytes.
+.It Cm tsess
+Control terminal session pointer.
+.It Cm tsiz
+Text size, in Kilobytes.
+.It Cm tt
 An abbreviation for the pathname of the controlling terminal, if any.
 The abbreviation consists of the two letters following
 .Dq /dev/tty ,
@@ -346,185 +483,33 @@ or, for the console,
 This is followed by a
 .Sq -
 if the process can no longer reach that
-controlling terminal (i.e., it has been revoked).
-.It wchan
+controlling terminal (i.e. it has been revoked).
+.It Cm tty
+Full name of control terminal.
+.It Cm ucomm
+Alias:
+.Cm comm .
+Name to be used for accounting.
+.It Cm uid
+Effective user ID.
+.It Cm upr
+Alias:
+.Cm usrpri .
+Scheduling priority on return from system call.
+.It Cm user
+User name (from
+.Cm uid ) .
+.It Cm vsz
+Alias:
+.Cm vsize .
+Virtual size, in Kilobytes.
+.It Cm wchan
 The event (an address in the system) on which a process waits.
 When printed numerically, the initial part of the address is
 trimmed off and the result is printed in hex; for example, 0x80324000 prints
 as 324000.
-.El
-.Pp
-When printing using the command keyword, a process that has exited and
-has a parent that has not yet waited for the process (in other words, a zombie)
-is listed as
-.Dq Aq defunct ,
-and a process which is blocked while trying
-to exit is listed as
-.Dq Aq exiting .
-.Nm
-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 depended
-on too much.
-The ucomm (accounting) keyword can, however, be depended on.
-.Sh KEYWORDS
-The following is a complete list of the available keywords and their
-meanings.
-Several of them have aliases (keywords which are synonyms).
-.Pp
-.Bl -tag -width sigignore -compact
-.It %cpu
-percentage CPU usage (alias pcpu)
-.It %mem
-percentage memory usage (alias pmem)
-.It acflag
-accounting flag (alias acflg)
-.It command
-command and arguments (alias args)
-.It cpu
-short-term CPU usage factor (for scheduling)
-.It cpuid
-CPU ID (zero on single processor systems)
-.It dsiz
-data size (in Kbytes)
-.It emul
-name of system call emulation environment
-.It flags
-the process flags, in hexadecimal (alias f)
-.It gid
-effective group
-.It group
-text name of effective group
-.Tn ID
-.It holdcnt
-number of holds on the process (if non-zero, process can't be swapped)
-.It inblk
-total blocks read (alias inblock)
-.It jobc
-job control count
-.It ktrace
-tracing flags
-.It ktracep
-tracing vnode
-.It lim
-memory usage limit
-.It logname
-login name of user who started the process
-(alias login)
-.It lstart
-time started
-.It majflt
-total page faults
-.It minflt
-total page reclaims
-.It msgrcv
-total messages received (reads from pipes/sockets)
-.It msgsnd
-total messages sent (writes on pipes/sockets)
-.It nice
-nice value (alias ni)
-.It nivcsw
-total involuntary context switches
-.It nsigs
-total signals taken (alias nsignals)
-.It nswap
-total swaps in/out
-.It nvcsw
-total voluntary context switches
-.It nwchan
-wait channel (as an address)
-.It oublk
-total blocks written (alias oublock)
-.It p_ru
-resource usage (valid only for zombie)
-.It paddr
-swap address
-.It pagein
-pageins (same as majflt)
-.It pgid
-process group number
-.It pid
-process
-.Tn ID
-.It ppid
-parent process
-.Tn ID
-.It pri
-scheduling priority
-.It re
-core residency time (in seconds; 127 = infinity)
-.It rgid
-real group
-.Tn ID
-.It rgroup
-text name of real group
-.Tn ID
-.It rlink
-reverse link on run queue, or 0
-.It rss
-resident set size
-.It rsz
-resident set size + (text size / text use count) (alias rssize)
-.It ruid
-real user
-.Tn ID
-.It ruser
-user name (from ruid)
-.It sess
-session pointer
-.It sig
-pending signals (alias pending)
-.It sigcatch
-caught signals (alias caught)
-.It sigignore
-ignored signals (alias ignored)
-.It sigmask
-blocked signals (alias blocked)
-.It sl
-sleep time (in seconds; 127 = infinity)
-.It ssiz
-stack size (in Kbytes)
-.It start
-time started (alias etime)
-.It state
-symbolic process state (alias stat)
-.It svgid
-saved GID from a setgid executable
-.It svuid
-saved UID from a setuid executable
-.It tdev
-control terminal device number
-.It time
-accumulated CPU time, user + system (alias cputime)
-.It tpgid
-control terminal process group
-.Tn ID
-.\".It trss
-.\"text resident set size (in Kbytes)
-.It tsess
-control terminal session pointer
-.It tsiz
-text size (in Kbytes)
-.It tt
-control terminal name (two letter abbreviation)
-.It tty
-full name of control terminal
-.It ucomm
-name to be used for accounting (alias comm)
-.It uid
-effective user
-.Tn ID
-.It upr
-scheduling priority on return from system call (alias usrpri)
-.It user
-user name (from uid)
-.It vsz
-virtual size in Kbytes (alias vsize)
-.It wchan
-wait channel (as a symbolic name)
-.It xstat
-exit or stop status (valid only for stopped or zombie process)
+.It Cm xstat
+Exit or stop status (valid only for stopped or zombie process).
 .El
 .Sh FILES
 .Bl -tag -width "/var/db/kvm_bsd.dbXXX" -compact
@@ -564,6 +549,25 @@ A
 command appeared in
 .At v3
 in section 8 of the manual.
+.Sh CAVEATS
+When printing using the
+.Cm command
+keyword, a process that has exited and
+has a parent that has not yet waited for the process (in other words, a zombie)
+is listed as
+.Dq Aq defunct ,
+and a process which is blocked while trying
+to exit is listed as
+.Dq Aq exiting .
+.Nm
+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 depended
+on too much.
+The
+.Cm ucomm
+(accounting) keyword can, however, be depended on.
 .Sh BUGS
 Since
 .Nm