4.4BSD snapshot (revision 8.1); add 1993 to copyright

[unix-history] / usr / src / usr.sbin / pstat / pstat.8

diff --git a/usr/src/usr.sbin/pstat/pstat.8 b/usr/src/usr.sbin/pstat/pstat.8
index 0f021e7..1d172eb 100644 (file)
--- a/usr/src/usr.sbin/pstat/pstat.8
+++ b/usr/src/usr.sbin/pstat/pstat.8
@@ -1,367 +1,286 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\"    @(#)pstat.8     6.2 (Berkeley) %G%
+.\"    @(#)pstat.8     8.1 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH PSTAT 8 ""
-.UC 4
-.SH NAME
-pstat \- print system facts
-.SH SYNOPSIS
-.B /etc/pstat
-.B \-aixptufT
-[
-.B suboptions
-] [
-.B system
-] [
-.B corefile
-]
-.SH DESCRIPTION
-.I Pstat
-interprets the contents of certain system tables.
+.\"     @(#)pstat.8    8.1 (Berkeley) %G%
+.\"
+.Dd 
+.Dt PSTAT 8
+.Os BSD 4
+.Sh NAME
+.Nm pstat
+.Nd display system data structures
+.Sh SYNOPSIS
+.Nm pstat
+.Op Fl Tfnstv
+.Op Fl M Ar core
+.Op Fl N Ar system
+.Sh DESCRIPTION
+.Nm Pstat
+displays open file entry, swap space utilization,
+terminal state, and vnode data structures.

 If
 If

-.I corefile
-is given, the tables are sought there, otherwise
+.Ar corefile
+is given, the information is sought there, otherwise

 in
 in

-.I /dev/kmem.
+.Pa /dev/kmem .

 The required namelist is taken from
 The required namelist is taken from

-.I /vmunix
+.Pa /vmunix

 unless 
 unless 

-.I system
+.Ar system

 is specified.
 is specified.

+The
+.Fl n
+option specifies that devices should be printed out by major/minor
+number rather than by name.
+.Pp

 Options are
 Options are

-.TP \w'WCHAN\ 'u
-.B \-a
-Under
-.BR \-p ,
-describe all process slots rather than just active ones.
-.TP
-.B \-i
-Print the inode table with the these headings:
-.IP LOC
-The core location of this table entry.
-.PD 0
-.IP FLAGS
-Miscellaneous state variables encoded thus:
-.RS
-.IP L
-locked
-.IP U
-update time
-.RI ( fs (5))
-must be corrected
-.IP A
-access time must be corrected
-.IP M
-file system is mounted here
-.IP W
-wanted by another process (L flag is on)
-.IP T
-contains a text file
-.IP C
-changed time must be corrected
-.IP S
-shared lock applied
-.IP E
-exclusive lock applied
-.IP Z
-someone waiting for an exclusive lock
-.RE
-.IP CNT
-Number of open file table entries for this inode.
-.IP DEV
-Major and minor device number of file system in which
-this inode resides.
-.IP RDC
-Reference count of shared locks on the inode.
-.IP WRC
-Reference count of exclusive locks on the inode (this may
-be > 1 if, for example, a file descriptor is inherited across a fork).
-.IP INO
-I-number within the device.
-.IP MODE
-Mode bits, see
-.IR chmod (2).
-.IP NLK
-Number of links to this inode.
-.IP UID
-User ID of owner.
-.IP SIZ/DEV
-Number of bytes in an ordinary file, or
-major and minor device of special file.
-.PD
-.TP
-.B \-x
-Print the text table with these headings:
-.IP LOC
+.Bl -tag -width indent
+.It Fl T
+Prints the number of used and free slots in the several system tables
+and is useful for checking to see how large system tables have become
+if the system is under heavy load.
+.It Fl f
+Print the open file table with these headings:
+.Bl -tag -width indent
+.It LOC

 The core location of this table entry.
 The core location of this table entry.

-.PD 0
-.IP FLAGS
+.It TYPE
+The type of object the file table entry points to.
+.It FLG

 Miscellaneous state variables encoded thus:
 Miscellaneous state variables encoded thus:

-.RS
-.IP T
-.IR ptrace (2)
-in effect
-.IP W
-text not yet written on swap device
-.IP L
-loading in progress
-.IP K
-locked
-.IP w
-wanted (L flag is on)
-.IP P
-resulted from demand-page-from-inode exec format (see
-.IR execve (2))
-.RE
-.PD
-.IP DADDR
-Disk address in swap, measured in multiples of 512 bytes.
-.IP CADDR
-Head of a linked list of loaded processes using this text segment.
-.IP RSS
-Size of resident text, measured in multiples of 512 bytes.
-.IP SIZE
-Size of text segment, measured in multiples of 512 bytes.
-.IP IPTR
-Core location of corresponding inode.
-.IP CNT
-Number of processes using this text segment.
-.IP CCNT
-Number of processes in core using this text segment.
-.IP FORW
-Forward link in free list.
-.IP BACK
-Backward link in free list.
-.PD
-.TP
-.B \-p
-Print process table for active processes with these headings:
-.IP LOC
-The core location of this table entry.
-.PD 0
-.IP S
-Run state encoded thus:
-.RS
-.IP 0
-no process
-.IP 1
-waiting for some event
-.IP 3
-runnable
-.IP 4
-being created
-.IP 5
-being terminated
-.IP 6
-stopped under trace
-.RE
-.IP F
-Miscellaneous state variables, or-ed together (hexadecimal):
-.RS
-.IP 0001 9n
-loaded
-.IP 0002
-the scheduler process
-.IP 0004
-locked for swap out
-.IP 0008
-swapped out
-.IP 0010
-traced
-.IP 0020
-used in tracing
-.      \".IP 000040
-.      \"locked in by
-.      \".IR lock (2).
-.IP 0080
-in page-wait
-.IP 0100
-prevented from swapping during
-.IR fork (2)
-.IP 0200
-will restore old mask after taking signal
-.IP 0400
-exiting
-.IP 0800
-doing physical i/o (bio.c)
-.IP 1000
-process resulted from a
-.IR vfork (2)
-which is not yet complete
-.IP 2000
-another flag for
-.IR vfork (2)
-.IP 4000
-process has no virtual memory, as it is a parent in the context of
-.IR vfork (2)
-.IP 8000
-process is demand paging data pages from its text inode.
-.RE
-.IP POIP
-number of pages currently being pushed out from this process.
-.IP PRI
-Scheduling priority, see
-.IR setpriority (2).
-.IP SIG
-Signals received (signals 1-32 coded in bits 0-31),
-.IP UID
-Real user ID.
-.IP SLP
-Amount of time process has been blocked.
-.IP TIM
-Time resident in seconds; times over 127 coded as 127.
-.IP CPU
-Weighted integral of CPU time, for scheduler.
-.IP NI
-Nice level,
-see
-.IR setpriority (2).
-.IP PGRP
-Process number of root of process group
-(the opener of the controlling terminal).
-.IP PID
-The process ID number.
-.IP PPID
-The process ID of parent process.
-.IP ADDR
-If in core, the page frame number of the first page of the `u-area' of
-the process.
-If swapped out, the position in the swap area
-measured in multiples of 512 bytes.
-.IP RSS
-Resident set size \- the number of physical page frames allocated
-to this process.
-.IP SRSS
-RSS at last swap (0 if never swapped).
-.IP SIZE
-Virtual size of process image (data+stack) in multiples of 512 bytes.
-.IP WCHAN
-Wait channel number of a waiting process.
-.IP LINK
-Link pointer in list of runnable processes.
-.IP TEXTP
-If text is pure, pointer to location of text table entry.
-.PD
-.TP
-.B \-t
+.Bl -tag -width indent
+.It R
+open for reading
+.It W
+open for writing
+.It A
+open for appending
+.It S
+shared lock present
+.It X
+exclusive lock present
+.It I
+signal pgrp when data ready
+.El
+.It CNT
+Number of processes that know this open file.
+.It MSG
+Number of messages outstanding for this file.
+.It DATA
+The location of the vnode table entry or socket structure for this file.
+.It OFFSET
+The file offset (see
+.Xr lseek 2 ) .
+.El
+.It Fl s
+Print information about swap space usage on all the 
+swap areas compiled into the kernel.
+The first column is the device name of the partition.  The next column is
+the total space available in the partition.  The 
+.Ar Used
+column indicates the total blocks used so far;  the 
+.Ar Available
+column indicates how much space is remaining on each partition.
+The
+.Ar Capacity
+reports the percentage of space used.
+.Pp
+If more than one partition is configured into the system, totals for all
+of the statistics will be reported in the final line of the report.
+.It Fl t

 Print table for terminals
 with these headings:
 Print table for terminals
 with these headings:

-.IP RAW
+.Bl -tag -width indent
+.It RAW

 Number of characters in raw input queue.
 Number of characters in raw input queue.

-.PD 0
-.IP CAN
+.It CAN

 Number of characters in canonicalized input queue.
 Number of characters in canonicalized input queue.

-.IP OUT
+.It OUT

 Number of characters in putput queue.
 Number of characters in putput queue.

-.IP MODE
+.It MODE

 See
 See

-.IR tty (4).
-.IP ADDR
+.Xr tty 4 .
+.It ADDR

 Physical device address.
 Physical device address.

-.IP DEL
+.It DEL

 Number of delimiters (newlines) in canonicalized input queue.
 Number of delimiters (newlines) in canonicalized input queue.

-.IP COL
+.It COL

 Calculated column position of terminal.
 Calculated column position of terminal.

-.IP STATE
+.It STATE

 Miscellaneous state variables encoded thus:
 Miscellaneous state variables encoded thus:

-.RS
-.IP T
+.Bl -tag -width indent
+.It T

 delay timeout in progress
 delay timeout in progress

-.IP W
+.It W

 waiting for open to complete
 waiting for open to complete

-.IP O
+.It O

 open
 open

-.IP F
+.It F

 outq has been flushed during DMA
 outq has been flushed during DMA

-.IP C
+.It C

 carrier is on
 carrier is on

-.IP B
+.It B

 busy doing output
 busy doing output

-.IP A
+.It A

 process is awaiting output
 process is awaiting output

-.IP X
+.It X

 open for exclusive use
 open for exclusive use

-.IP S
+.It S

 output stopped
 output stopped

-.IP H
+.It H

 hangup on close
 hangup on close

-.RE
-.IP PGRP
+.El
+.It PGRP

 Process group for which this is controlling terminal.
 Process group for which this is controlling terminal.

-.IP DISC
-Line discipline; blank is old tty OTTYDISC or ``new tty'' for NTTYDISC
-or ``net'' for NETLDISC (see
-.IR bk (4)).
-.PD
-.TP
-.B \-u
-print information about a user process;
-the next argument is its address as given
-by
-.IR ps (1).
-The process must be in main memory, or the file used can
-be a core image and the address 0.
-.TP
-.B \-f
-Print the open file table with these headings:
-.IP LOC
+.It DISC
+Line discipline; blank is old tty
+OTTYDISC
+or
+.Ql new tty
+for
+NTTYDISC
+or
+.Ql net
+for
+NETLDISC
+(see
+.Xr bk 4 ) .
+.El
+.It Fl v
+Print the active vnodes.  Each group of vnodes coresponding
+to a particular filesystem is preceded by a two line header.  The
+first line consists of the following:
+.Pp
+.Df I
+.No *** MOUNT Em fstype from 
+on
+.Em on fsflags
+.De
+.Pp
+where
+.Em fstype
+is one of
+.Em ufs , nfs , mfs , or pc ;
+.Em from
+is the filesystem is mounted from;
+.Em on
+is the directory
+the filesystem is mounted on; and
+.Em fsflags
+is a list
+of optional flags applied to the mount (see
+.Xr mount 8 ) .
+.The second line is a header for the individual fields ,
+the first part of which are fixed, and the second part are filesystem
+type specific.  The headers common to all vnodes are:
+.Bl -tag -width indent
+.It ADDR
+Location of this vnode.
+.It TYP
+File type.
+.It VFLAG
+.Pp
+A list of letters representing vnode flags:
+.Bl -tag -width indent
+.It R
+\- VROOT
+.It T
+\- VTEXT
+.It L
+\- VXLOCK
+.It W
+\- VXWANT
+.It E
+\- VEXLOCK
+.It S
+\- VSHLOCK
+.It T
+\- VLWAIT
+.It A
+\- VALIASED
+.It B
+\- VBWAIT
+.El
+.Pp
+.It LOC

 The core location of this table entry.
 The core location of this table entry.

-.IP TYPE
-The type of object the file table entry points to.
-.PD 0
-.IP FLG
+.It FLAGS

 Miscellaneous state variables encoded thus:
 Miscellaneous state variables encoded thus:

-.RS
-.IP R
-open for reading
-.IP W
-open for writing
-.IP A
-open for appending
-.IP S
-shared lock present
-.IP X
-exclusive lock present
-.IP I
-signal pgrp when data ready
-.RE
-.IP CNT
-Number of processes that know this open file.
-.IP MSG
-Number of messages outstanding for this file.
-.IP DATA
-The location of the inode table entry or socket structure for this file.
-.IP OFFSET
-The file offset (see
-.IR lseek (2)).
-.PD
-.PP
-.B \-s
-print information about swap space usage: the number of (1k byte) pages used
-and free is given as well as the number of used pages which belong
-to text images.
-.PP
-.B \-T
-prints the number of used and free slots in the several system tables
-and is useful for checking to see how full system tables have become if the
-system is under heavy load.
-.SH FILES
-.ta \w'/dev/kmem  'u
-/vmunix        namelist
-.br
-/dev/kmem      default source of tables
-.SH SEE ALSO
-ps(1),
-stat(2),
-fs(5)
-.br
-K. Thompson,
-.I UNIX Implementation
-.SH BUGS
-It would be very useful if the system recorded \*(lqmaximum occupancy\*(rq
-on the tables reported by
-.B \-T;
-even more useful if these tables were dynamically allocated.
+.Bl -tag -width indent
+.It L
+locked
+.It U
+update time
+.Pq Xr fs 5
+must be corrected
+.It A
+access time must be corrected
+.It W
+wanted by another process (L flag is on)
+.It C
+changed time must be corrected
+.It S
+shared lock applied
+.It E
+exclusive lock applied
+.It Z
+someone waiting for a lock
+.It M
+contains modifications
+.It R
+has a rename in progress
+.El
+.It CNT
+Number of open file table entries for this inode.
+.It DEV
+Major and minor device number of file system in which
+this inode resides.
+.It RDC
+Reference count of shared locks on the inode.
+.It WRC
+Reference count of exclusive locks on the inode (this may
+be > 1 if, for example, a file descriptor is inherited across a fork).
+.It INO
+I-number within the device.
+.It MODE
+Mode bits, see
+.Xr chmod 2 .
+.It NLK
+Number of links to this inode.
+.It UID
+User ID of owner.
+.It SIZ/DEV
+Number of bytes in an ordinary file, or
+major and minor device of special file.
+.El
+.El
+.Sh FILES
+.Bl -tag -width /dev/kmemxxx -compact
+.It Pa /vmunix
+namelist
+.It Pa /dev/kmem
+default source of tables
+.El
+.Sh SEE ALSO
+.Xr iostat 1 ,
+.Xr ps 1 ,
+.Xr systat 1 ,
+.Xr vmstat 1 ,
+.Xr stat 2 ,
+.Xr fs 5 ,
+.Rs
+.Rt Tn UNIX Rt Implementation ,
+.Ra K. Thompson
+.Re
+.Sh BUGS
+Swap statistics are reported for all swap partitions compiled into the kernel,
+regardless of whether those partitions are being used.
+.Pp
+Does not understand NFS swap servers.
+.Sh HISTORY
+The
+.Nm pstat
+command appeared in 4.0BSD.