Module Name: src
Committed By: uwe
Date: Wed Mar 29 21:44:35 UTC 2023
Modified Files:
src/usr.bin/systat: systat.1
Log Message:
systat(1): try to give this page a quick facelift
... too bad what it really needs is reconstructive surgery. I tried
to fix the most obvious problems (unsorted lists, obviously wrong
markup, pleonastic wording that drowns out useful information in
repetition and lifetime supply of quote marks).
This page really needs a native speaker to take some loving care of it.
To generate a diff of this commit:
cvs rdiff -u -r1.53 -r1.54 src/usr.bin/systat/systat.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/systat/systat.1
diff -u src/usr.bin/systat/systat.1:1.53 src/usr.bin/systat/systat.1:1.54
--- src/usr.bin/systat/systat.1:1.53 Wed Mar 29 19:40:18 2023
+++ src/usr.bin/systat/systat.1 Wed Mar 29 21:44:35 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: systat.1,v 1.53 2023/03/29 19:40:18 kre Exp $
+.\" $NetBSD: systat.1,v 1.54 2023/03/29 21:44:35 uwe Exp $
.\"
.\" Copyright (c) 1985, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -29,7 +29,7 @@
.\"
.\" @(#)systat.1 8.2 (Berkeley) 12/30/93
.\"
-.Dd August 21, 2021
+.Dd March 29, 2023
.Dt SYSTAT 1
.Os
.Sh NAME
@@ -43,17 +43,18 @@
.Op Fl t Ar turns
.Op Fl w Ar wait
.Op Ar display
-.Op Ar refresh-interval
+.Op Ar wait
.Sh DESCRIPTION
.Nm
displays various system statistics in a screen oriented fashion
-using the curses screen display library,
-.Xr curses 3 .
+using the
+.Xr curses 3
+screen display library.
.Pp
While
.Nm
-is running the screen is usually divided into two windows (an exception
-is the vmstat display which uses the entire screen).
+is running the screen is usually divided into two windows
+.Pq an exception is the vmstat display which uses the entire screen .
The upper window depicts the current system load average.
The information displayed in the lower window may vary, depending on
user commands.
@@ -65,27 +66,27 @@ displays the processes getting the large
in the lower window.
Other displays show more detailed process information,
swap space usage,
-disk usage statistics (a la
-.Xr df 1 ) ,
-disk I/O statistics (a la
-.Xr iostat 8 ) ,
-virtual memory statistics (a la
-.Xr vmstat 1 ) ,
-network
-.Qq Ic mbufs
-utilization, network
-.Qq Ic ifstat
-traffic, and network connections (a la
-.Xr netstat 1 ) .
+disk usage statistics
+.Pq a\~la Xr df 1 ,
+disk I/O statistics
+.Pq a\~la Xr iostat 8 ,
+virtual memory statistics
+.Pq a\~la Xr vmstat 1 ,
+network mbuf utilization,
+network interface traffic,
+and network connections
+.Pq a\~la Xr netstat 1 .
.Pp
Input is interpreted at two different levels.
-A ``global'' command interpreter processes all keyboard input.
+A global command interpreter processes all keyboard input.
If this command interpreter fails to recognize a command, the
input line is passed to a per-display command interpreter.
This allows each display to have certain display-specific commands.
.Pp
Command line options:
-.Bl -tag -width "refresh_interval"
+.Bl -tag -width Fl
+.It Fl b
+Show the chosen display once and exit.
.It Fl M Ar core
Extract values associated with the name list from
.Ar core
@@ -96,22 +97,26 @@ Extract the name list from
.Ar system
instead of the default
.Pa /netbsd .
-.It Fl b
-Show the chosen display once and exit.
.It Fl n
Do not resolve IP addresses into string hostnames
-.Pq FQDNs
-on
-.Ic netstat .
+.Pf ( Tn FQDN Ns s ) .
It has the same effect as
.Ic numbers
subcommand in
.Ic netstat .
-.It Fl w Ar wait
-See
-.Ar refresh-interval .
.It Fl t Ar turns
-How many refreshes to show each screen in 'all' display mode.
+How many refresh cycles to show each screen in
+.Sq all
+display mode.
+The default is 2.
+.It Fl w Ar wait
+Set the screen refresh interval to
+.Ar wait
+seconds.
+Floating point numbers are accepted.
+The default is 1\~second.
+.It Fl z
+Display 0 instead of space when there is no data.
.It Ar display
The
.Ar display
@@ -136,30 +141,23 @@ or
.Ic vmstat .
These displays can also be requested interactively and are described in
full detail below.
-.It Ar refresh-interval
-The
-.Ar refresh-interval
-specifies the screen refresh time interval in seconds.
-This is provided for backwards compatibility, and overrides the
-.Ar refresh-interval
-specified with the
-.Fl w
-flag.
-.It Fl z
-Display 0 instead of space when there is no data.
+.It Ar wait
+The same as
+.Fl w Ar wait .
+This form is provided for backwards compatibility.
.El
.Pp
Certain characters cause immediate action by
.Nm .
These are
-.Bl -tag -width Fl
+.Bl -tag -width Ic
.It Ic \&^L
Refresh the screen.
.It Ic \&^G
-Print the name of the current ``display'' being shown in
+Print the name of the current display being shown in
the lower window and the refresh interval.
.It Ic \&^Z
-Stop
+Suspend
.Nm .
.It Ic \&? , Ic h
Print the names of the available displays on the command line.
@@ -170,15 +168,15 @@ While entering a command the current cha
and line kill characters may be used.
.El
.Pp
-The following commands are interpreted by the ``global''
+The following commands are interpreted by the global
command interpreter.
-.Bl -tag -width Fl
-.It Ic help Ar key
+.Bl -tag -width Ic
+.It Ic help Op Ar key
Print the names of the available displays on the command line.
It will print long names as
-.Dq Ic inet.* .
+.Ql inet.* .
To print items under
-.Dq Ic inet ,
+.Ic inet ,
give
.Ic inet
as
@@ -186,19 +184,18 @@ as
.It Ic load
Print the load average over the past 1, 5, and 15 minutes
on the command line.
-.It Ic stop
-Stop refreshing the screen.
+.It Ic quit
+Exit
+.Nm .
+.Pq This may be abbreviated to Ic q .
.It Oo Ic start Oc Oo Ar number Oc
Start (continue) refreshing the screen.
If a second, numeric, argument is provided it is interpreted as a
refresh interval in seconds.
Supplying only a number will set the refresh interval to this
value.
-.It Ic quit
-Exit
-.Nm .
-(This may be abbreviated to
-.Ic q . )
+.It Ic stop
+Stop refreshing the screen.
.El
.Pp
The available displays are:
@@ -226,7 +223,7 @@ The following commands are specific to t
.Ic df
display:
.Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width Fl
.It Cm all
Displays information for all filesystems, including
kernfs, procfs and null-mounts.
@@ -251,33 +248,43 @@ peak
traffic columns can be altered by the
.Ic scale
command.
-.Bl -tag -width ".Cm scale Op Ar units"
+.Bl -tag -width Cm
.It Cm scale Op Ar units
Modify the scale used to display the current and peak traffic over all
interfaces.
-The following units are recognised: kbit, kbyte, mbit,
-mbyte, gbit, gbyte and auto.
+The following units are recognised:
+.Ic kbit , kbyte , mbit , mbyte , gbit , gbyte
+and
+.Ic auto .
.It Cm pps
-Show statistics in packets per second instead of bytes/bits per second.
+Show statistics in packets per second instead of bytes or bits per second.
A subsequent call of
.Ic pps
switches this mode off.
-.It Cm match Op Ar patterns
-Display only interfaces that match pattern provided as an argument.
-Patterns should be in shell syntax separated by whitespaces or commas.
+.It Cm match Op Ar pattern ...
+Display only interfaces that match
+.Ar pattern\^ Ns s
+provided as an argument.
+Patterns should be in shell
+.Xr glob 7
+syntax separated by whitespaces or commas.
If this command is called without arguments then all interfaces are displayed.
For example:
.Pp
.Dl match re0, bge1
.Pp
-This will display re0 and bge1 interfaces.
+This will display
+.Li re0
+and
+.Li bge1
+interfaces.
.Pp
-.Dl match re*, bge*, lo0
+.Dl match re* bge* lo0
.Pp
This will display all
-.Ic re
+.Li re
interfaces, all
-.Ic bge
+.Li bge
interfaces and the loopback interface.
.El
.It Ic inet.icmp
@@ -287,16 +294,19 @@ Display IPv4 and UDP statistics.
.It Ic inet.tcp
Display TCP statistics.
.It Ic inet.tcpsyn
-Display statistics about the TCP ``syncache''.
+Display statistics about the TCP syncache.
.It Ic inet6.ip6
Display IPv6 statistics.
.It Ic iostat
Display, in the lower window, statistics about processor use
and disk throughput.
Statistics on processor use appear as bar graphs of the amount of
-time executing in user mode (``user''), in user mode running low
-priority processes (``nice''), in system mode (``system''), and
-idle (``idle'').
+time executing in user mode,
+in user mode running low priority
+.Pq Dq nice
+processes,
+in system mode,
+and idle.
Statistics on disk throughput show, for each drive, kilobytes of
data transferred, number of disk transactions performed, and time
spent in disk accesses in milliseconds.
@@ -329,62 +339,74 @@ for particular uses, i.e. data, socket s
.It Ic netstat
Display, in the lower window, network connections.
By default, network servers awaiting requests are not displayed.
-Each address is displayed in the format ``host.port'', with each
+Each address is displayed in the format
+.Ar host Ns Li . Ns Ar port ,
+with each
shown symbolically, when possible.
It is possible to have addresses displayed numerically,
limit the display to a set of ports, hosts, and/or protocols
-(the minimum unambiguous prefix may be supplied):
+.Pq the minimum unambiguous prefix may be supplied :
.Pp
-.Bl -tag -width Ar -compact
+.Bl -tag -width Cm
.It Cm all
-Toggle the displaying of server processes awaiting requests (this
-is the equivalent of the
+Toggle the displaying of server processes awaiting requests
+.Po
+this is the equivalent of the
.Fl a
flag to
-.Ar netstat 1 ) .
-.It Cm numbers
-Display network addresses numerically.
-.It Cm names
-Display network addresses symbolically.
-.It Ar protocol
-Display only network connections using the indicated protocol
-(currently either ``tcp'' or ``udp'').
-.It Cm ignore Op Ar items
-Do not display information about connections associated with
-the specified hosts or ports.
-Hosts and ports may be specified by name (``vangogh'', ``ftp''),
-or numerically.
-Host addresses use the Internet dot notation (``128.32.0.9'').
-Multiple items may be specified with a single command by separating
-them with spaces.
+.Xr netstat 1
+.Pc .
.It Cm display Op Ar items
Display information about the connections associated with the
specified hosts or ports.
+Hosts and ports may be specified by name
+.Pq Ql vangogh , ftp ,
+or numerically.
+Host addresses use the Internet dot notation
+.Pq Ql 128.32.0.9 .
+Multiple items may be specified with a single command by separating
+them with spaces.
+.It Cm ignore Op Ar items
+Do not display information about connections associated with
+the specified hosts or ports.
As for
-.Ar ignore ,
-.Op Ar items
+.Ic display ,
+the
+.Ar items
may be names or numbers.
-.It Cm show Op Ar ports\&|hosts
+.It Cm names
+Display network addresses symbolically.
+.It Cm numbers
+Display network addresses numerically.
+.It Ar protocol
+Display only network connections using the indicated protocol
+.Po
+currently either
+.Ic tcp
+or
+.Ic udp
+.Pc .
+.It Cm show Op Cm hosts No \&| Cm ports
Show, on the command line, the currently selected protocols,
hosts, and ports.
-Hosts and ports which are being ignored are prefixed with a `!'.
+Hosts and ports which are being ignored are prefixed with a
+.Ql \&! .
If
-.Ar ports
+.Cm ports
or
-.Ar hosts
+.Cm hosts
is supplied as an argument to
.Cm show ,
then only the requested information will be displayed.
.It Cm reset
-Reset the port, host, and protocol matching mechanisms to the default
-(any protocol, port, or host).
+Reset the port, host, and protocol filters, show everything.
.El
.It Ic pigs
Display, in the lower window, those processes which are getting the
largest portion of the processor (the default display).
When less than 100% of the
processor is scheduled to user processes, the remaining time
-is accounted to the ``idle'' process.
+is accounted to the idle process.
.It Ic ps
Display, in the lower window, the same information provided
by the command
@@ -402,7 +424,9 @@ Limit the list of processes displayed to
.Ar name .
If
.Ar name
-is specified as `+', processes owned by any user are displayed (default).
+is specified as
+.Ql \&+ ,
+processes owned by any user are displayed (default).
.El
.It Ic swap
Show information about swap space usage on all the
@@ -411,7 +435,7 @@ swap areas configured with
The first column is the device name of the partition.
The next column is the total space available in the partition.
The
-.Ar Used
+.Dq Used
column indicates the total blocks used so far;
the graph shows the percentage of space in use on each partition.
If there are more than one swap partition in use,
@@ -586,7 +610,10 @@ Only devices that have interrupted at le
.El
.Pp
Commands to switch between displays may be abbreviated to the
-minimum unambiguous prefix; for example, ``io'' for ``iostat''.
+minimum unambiguous prefix; for example,
+.Ic io
+for
+.Ic iostat .
Certain information may be discarded when the screen size is
insufficient for display.
For example, on a machine with 10 drives the
@@ -650,11 +677,13 @@ For network names.
For port names.
.El
.Sh NOTES
-Much of the information that
+Most of the information shown by
.Nm
.Ic vmstat
-uses is obtained from
-.Cm struct vmmeter cnt .
+is obtained from the
+.Ql vm.vmmeter
+.Xr sysctl 7
+node.
.Sh SEE ALSO
.Xr df 1 ,
.Xr netstat 1 ,
