Annotation of src/usr.bin/systat/systat.1, Revision 1.1
1.1 ! deraadt 1: .\" $NetBSD: systat.1,v 1.5 1995/09/27 19:46:12 jtc Exp $
! 2: .\"
! 3: .\" Copyright (c) 1985, 1990, 1993
! 4: .\" The Regents of the University of California. All rights reserved.
! 5: .\"
! 6: .\" Redistribution and use in source and binary forms, with or without
! 7: .\" modification, are permitted provided that the following conditions
! 8: .\" are met:
! 9: .\" 1. Redistributions of source code must retain the above copyright
! 10: .\" notice, this list of conditions and the following disclaimer.
! 11: .\" 2. Redistributions in binary form must reproduce the above copyright
! 12: .\" notice, this list of conditions and the following disclaimer in the
! 13: .\" documentation and/or other materials provided with the distribution.
! 14: .\" 3. All advertising materials mentioning features or use of this software
! 15: .\" must display the following acknowledgement:
! 16: .\" This product includes software developed by the University of
! 17: .\" California, Berkeley and its contributors.
! 18: .\" 4. Neither the name of the University nor the names of its contributors
! 19: .\" may be used to endorse or promote products derived from this software
! 20: .\" without specific prior written permission.
! 21: .\"
! 22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
! 23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
! 26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 32: .\" SUCH DAMAGE.
! 33: .\"
! 34: .\" @(#)systat.1 8.2 (Berkeley) 12/30/93
! 35: .\"
! 36: .Dd December 30, 1993
! 37: .Dt SYSTAT 1
! 38: .Os BSD 4.3
! 39: .Sh NAME
! 40: .Nm systat
! 41: .Nd display system statistics on a crt
! 42: .Sh SYNOPSIS
! 43: .Nm systat
! 44: .Op Fl display
! 45: .Op Ar refresh-interval
! 46: .Sh DESCRIPTION
! 47: .Nm Systat
! 48: displays various system statistics in a screen oriented fashion
! 49: using the curses screen display library,
! 50: .Xr curses 3 .
! 51: .Pp
! 52: While
! 53: .Nm systat
! 54: is running the screen is usually divided into two windows (an exception
! 55: is the vmstat display which uses the entire screen). The
! 56: upper window depicts the current system load average. The
! 57: information displayed in the lower window may vary, depending on
! 58: user commands. The last line on the screen is reserved for user
! 59: input and error messages.
! 60: .Pp
! 61: By default
! 62: .Nm systat
! 63: displays the processes getting the largest percentage of the processor
! 64: in the lower window. Other displays show swap space usage, disk
! 65: .Tn I/O
! 66: statistics (a la
! 67: .Xr iostat 8 ) ,
! 68: virtual memory statistics (a la
! 69: .Xr vmstat 8 ) ,
! 70: network ``mbuf'' utilization, and network connections (a la
! 71: .Xr netstat 1 ) .
! 72: .Pp
! 73: Input is interpreted at two different levels.
! 74: A ``global'' command interpreter processes all keyboard input.
! 75: If this command interpreter fails to recognize a command, the
! 76: input line is passed to a per-display command interpreter. This
! 77: allows each display to have certain display-specific commands.
! 78: .Pp
! 79: Command line options:
! 80: .Bl -tag -width "refresh_interval"
! 81: .It Fl Ns Ar display
! 82: The
! 83: .Fl
! 84: flag expects
! 85: .Ar display
! 86: to be one of:
! 87: .Ic pigs ,
! 88: .Ic iostat ,
! 89: .Ic swap ,
! 90: .Ic mbufs ,
! 91: .Ic vmstat
! 92: or
! 93: .Ic netstat .
! 94: These displays can also be requested interactively (without the
! 95: .Dq Fl )
! 96: and are described in
! 97: full detail below.
! 98: .It Ar refresh-interval
! 99: The
! 100: .Ar refresh-value
! 101: specifies the screen refresh time interval in seconds.
! 102: .El
! 103: .Pp
! 104: Certain characters cause immediate action by
! 105: .Nm systat .
! 106: These are
! 107: .Bl -tag -width Fl
! 108: .It Ic \&^L
! 109: Refresh the screen.
! 110: .It Ic \&^G
! 111: Print the name of the current ``display'' being shown in
! 112: the lower window and the refresh interval.
! 113: .It Ic \&^Z
! 114: Stop
! 115: .Nm systat .
! 116: .It Ic \&:
! 117: Move the cursor to the command line and interpret the input
! 118: line typed as a command. While entering a command the
! 119: current character erase, word erase, and line kill characters
! 120: may be used.
! 121: .El
! 122: .Pp
! 123: The following commands are interpreted by the ``global''
! 124: command interpreter.
! 125: .Bl -tag -width Fl
! 126: .It Ic help
! 127: Print the names of the available displays on the command line.
! 128: .It Ic load
! 129: Print the load average over the past 1, 5, and 15 minutes
! 130: on the command line.
! 131: .It Ic stop
! 132: Stop refreshing the screen.
! 133: .It Xo
! 134: .Op Ic start
! 135: .Op Ar number
! 136: .Xc
! 137: Start (continue) refreshing the screen. If a second, numeric,
! 138: argument is provided it is interpreted as a refresh interval
! 139: (in seconds).
! 140: Supplying only a number will set the refresh interval to this
! 141: value.
! 142: .It Ic quit
! 143: Exit
! 144: .Nm systat .
! 145: (This may be abbreviated to
! 146: .Ic q . )
! 147: .El
! 148: .Pp
! 149: The available displays are:
! 150: .Bl -tag -width Ic
! 151: .It Ic pigs
! 152: Display, in the lower window, those processes resident in main
! 153: memory and getting the
! 154: largest portion of the processor (the default display).
! 155: When less than 100% of the
! 156: processor is scheduled to user processes, the remaining time
! 157: is accounted to the ``idle'' process.
! 158: .It Ic iostat
! 159: Display, in the lower window, statistics about processor use
! 160: and disk throughput. Statistics on processor use appear as
! 161: bar graphs of the amount of time executing in user mode (``user''),
! 162: in user mode running low priority processes (``nice''), in
! 163: system mode (``system''), and idle (``idle''). Statistics
! 164: on disk throughput show, for each drive, kilobytes of data transferred,
! 165: number of disk transactions performed, and average seek time
! 166: (in milliseconds). This information may be displayed as
! 167: bar graphs or as rows of numbers which scroll downward. Bar
! 168: graphs are shown by default;
! 169: .Pp
! 170: The following commands are specific to the
! 171: .Ic iostat
! 172: display; the minimum unambiguous prefix may be supplied.
! 173: .Pp
! 174: .Bl -tag -width Fl -compact
! 175: .It Cm numbers
! 176: Show the disk
! 177: .Tn I/O
! 178: statistics in numeric form. Values are
! 179: displayed in numeric columns which scroll downward.
! 180: .It Cm bars
! 181: Show the disk
! 182: .Tn I/O
! 183: statistics in bar graph form (default).
! 184: .It Cm msps
! 185: Toggle the display of average seek time (the default is to
! 186: not display seek times).
! 187: .El
! 188: .It Ic swap
! 189: Show information about swap space usage on all the
! 190: swap areas compiled into the kernel.
! 191: The first column is the device name of the partition.
! 192: The next column is the total space available in the partition.
! 193: The
! 194: .Ar Used
! 195: column indicates the total blocks used so far;
! 196: the graph shows the percentage of space in use on each partition.
! 197: If there are more than one swap partition in use,
! 198: a total line is also shown.
! 199: Areas known to the kernel, but not in use are shown as not available.
! 200: .It Ic mbufs
! 201: Display, in the lower window, the number of mbufs allocated
! 202: for particular uses, i.e. data, socket structures, etc.
! 203: .It Ic vmstat
! 204: Take over the entire display and show a (rather crowded) compendium
! 205: of statistics related to virtual memory usage, process scheduling,
! 206: device interrupts, system name translation cacheing, disk
! 207: .Tn I/O
! 208: etc.
! 209: .Pp
! 210: The upper left quadrant of the screen shows the number
! 211: of users logged in and the load average over the last one, five,
! 212: and fifteen minute intervals.
! 213: Below this line are statistics on memory utilization.
! 214: The first row of the table reports memory usage only among
! 215: active processes, that is processes that have run in the previous
! 216: twenty seconds.
! 217: The second row reports on memory usage of all processes.
! 218: The first column reports on the number of physical pages
! 219: claimed by processes.
! 220: The second column reports the number of physical pages that
! 221: are devoted to read only text pages.
! 222: The third and fourth columns report the same two figures for
! 223: virtual pages, that is the number of pages that would be
! 224: needed if all processes had all of their pages.
! 225: Finally the last column shows the number of physical pages
! 226: on the free list.
! 227: .Pp
! 228: Below the memory display is the disk usage display.
! 229: It reports the number of seeks, transfers, and number
! 230: of kilobyte blocks transferred per second averaged over the
! 231: refresh period of the display (by default, five seconds).
! 232: For some disks it also reports the average milliseconds per seek.
! 233: Note that the system only keeps statistics on at most four disks.
! 234: .Pp
! 235: Below the disk display is a list of the
! 236: average number of processes (over the last refresh interval)
! 237: that are runnable (`r'), in page wait (`p'),
! 238: in disk wait other than paging (`d'),
! 239: sleeping (`s'), and swapped out but desiring to run (`w').
! 240: Below the queue length listing is a numerical listing and
! 241: a bar graph showing the amount of
! 242: system (shown as `='), user (shown as `>'),
! 243: nice (shown as `-'), and idle time (shown as ` ').
! 244: .Pp
! 245: At the bottom left are statistics on name translations.
! 246: It lists the number of names translated in the previous interval,
! 247: the number and percentage of the translations that were
! 248: handled by the system wide name translation cache, and
! 249: the number and percentage of the translations that were
! 250: handled by the per process name translation cache.
! 251: .Pp
! 252: Under the date in the upper right hand quadrant are statistics
! 253: on paging and swapping activity.
! 254: The first two columns report the average number of pages
! 255: brought in and out per second over the last refresh interval
! 256: due to page faults and the paging daemon.
! 257: The third and fourth columns report the average number of pages
! 258: brought in and out per second over the last refresh interval
! 259: due to swap requests initiated by the scheduler.
! 260: The first row of the display shows the average
! 261: number of disk transfers per second over the last refresh interval;
! 262: the second row of the display shows the average
! 263: number of pages transferred per second over the last refresh interval.
! 264: .Pp
! 265: Below the paging statistics is a line listing the average number of
! 266: total reclaims ('Rec'),
! 267: intransit blocking page faults (`It'),
! 268: swap text pages found in free list (`F/S'),
! 269: file system text pages found in free list (`F/F'),
! 270: reclaims from free list
! 271: pages freed by the clock daemon (`Fre'),
! 272: and sequential process pages freed (`SFr')
! 273: per second over the refresh interval.
! 274: .Pp
! 275: Below this line are statistics on the average number of
! 276: zero filled pages (`zf') and demand filled text pages (`xf')
! 277: per second over the refresh period.
! 278: The first row indicates the number of requests that were
! 279: resolved, the second row shows the number that were set up,
! 280: and the last row shows the percentage of setup requests that were
! 281: actually used.
! 282: Note that this percentage is usually less than 100%,
! 283: however it may exceed 100% if a large number of requests
! 284: are actually used long after they were set up during a
! 285: period when no new pages are being set up.
! 286: Thus this figure is most interesting when observed over
! 287: a long time period, such as from boot time
! 288: (see below on getting such a display).
! 289: .Pp
! 290: Below the page fill statistics is a column that
! 291: lists the average number of context switches (`Csw'),
! 292: traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'),
! 293: characters output to DZ ports using
! 294: .No pseudo Ns -DMA
! 295: (`Pdm'),
! 296: network software interrupts (`Sof'),
! 297: page faults (`Flt'), pages scanned by the page daemon (`Scn'),
! 298: and revolutions of the page daemon's hand (`Rev')
! 299: per second over the refresh interval.
! 300: .Pp
! 301: Running down the right hand side of the display is a breakdown
! 302: of the interrupts being handled by the system.
! 303: At the top of the list is the total interrupts per second
! 304: over the time interval.
! 305: The rest of the column breaks down the total on a device
! 306: by device basis.
! 307: Only devices that have interrupted at least once since boot time are shown.
! 308: .Pp
! 309: The following commands are specific to the
! 310: .Ic vmstat
! 311: display; the minimum unambiguous prefix may be supplied.
! 312: .Pp
! 313: .Bl -tag -width Ar -compact
! 314: .It Cm boot
! 315: Display cumulative statistics since the system was booted.
! 316: .It Cm run
! 317: Display statistics as a running total from the point this
! 318: command is given.
! 319: .It Cm time
! 320: Display statistics averaged over the refresh interval (the default).
! 321: .It Cm zero
! 322: Reset running statistics to zero.
! 323: .El
! 324: .It Ic netstat
! 325: Display, in the lower window, network connections. By default,
! 326: network servers awaiting requests are not displayed. Each address
! 327: is displayed in the format ``host.port'', with each shown symbolically,
! 328: when possible. It is possible to have addresses displayed numerically,
! 329: limit the display to a set of ports, hosts, and/or protocols
! 330: (the minimum unambiguous prefix may be supplied):
! 331: .Pp
! 332: .Bl -tag -width Ar -compact
! 333: .It Cm all
! 334: Toggle the displaying of server processes awaiting requests (this
! 335: is the equivalent of the
! 336: .Fl a
! 337: flag to
! 338: .Ar netstat 1 ) .
! 339: .It Cm numbers
! 340: Display network addresses numerically.
! 341: .It Cm names
! 342: Display network addresses symbolically.
! 343: .It Ar protocol
! 344: Display only network connections using the indicated protocol
! 345: (currently either ``tcp'' or ``udp'').
! 346: .It Cm ignore Op Ar items
! 347: Do not display information about connections associated with
! 348: the specified hosts or ports. Hosts and ports may be specified
! 349: by name (``vangogh'', ``ftp''), or numerically. Host addresses
! 350: use the Internet dot notation (``128.32.0.9''). Multiple items
! 351: may be specified with a single command by separating them with
! 352: spaces.
! 353: .It Cm display Op Ar items
! 354: Display information about the connections associated with the
! 355: specified hosts or ports. As for
! 356: .Ar ignore ,
! 357: .Op Ar items
! 358: may be names or numbers.
! 359: .It Cm show Op Ar ports\&|hosts
! 360: Show, on the command line, the currently selected protocols,
! 361: hosts, and ports. Hosts and ports which are being ignored
! 362: are prefixed with a `!'. If
! 363: .Ar ports
! 364: or
! 365: .Ar hosts
! 366: is supplied as an argument to
! 367: .Cm show ,
! 368: then only the requested information will be displayed.
! 369: .It Cm reset
! 370: Reset the port, host, and protocol matching mechanisms to the default
! 371: (any protocol, port, or host).
! 372: .El
! 373: .El
! 374: .Pp
! 375: Commands to switch between displays may be abbreviated to the
! 376: minimum unambiguous prefix; for example, ``io'' for ``iostat''.
! 377: Certain information may be discarded when the screen size is
! 378: insufficient for display. For example, on a machine with 10
! 379: drives the
! 380: .Ic iostat
! 381: bar graph displays only 3 drives on a 24 line terminal. When
! 382: a bar graph would overflow the allotted screen space it is
! 383: truncated and the actual value is printed ``over top'' of the bar.
! 384: .Pp
! 385: The following commands are common to each display which shows
! 386: information about disk drives. These commands are used to
! 387: select a set of drives to report on, should your system have
! 388: more drives configured than can normally be displayed on the
! 389: screen.
! 390: .Pp
! 391: .Bl -tag -width Tx -compact
! 392: .It Cm ignore Op Ar drives
! 393: Do not display information about the drives indicated. Multiple
! 394: drives may be specified, separated by spaces.
! 395: .It Cm display Op Ar drives
! 396: Display information about the drives indicated. Multiple drives
! 397: may be specified, separated by spaces.
! 398: .El
! 399: .Sh FILES
! 400: .Bl -tag -width /etc/networks -compact
! 401: .It Pa /netbsd
! 402: For the namelist.
! 403: .It Pa /dev/kmem
! 404: For information in main memory.
! 405: .It Pa /dev/drum
! 406: For information about swapped out processes.
! 407: .It Pa /etc/hosts
! 408: For host names.
! 409: .It Pa /etc/networks
! 410: For network names.
! 411: .It Pa /etc/services
! 412: For port names.
! 413: .El
! 414: .Sh HISTORY
! 415: The
! 416: .Nm systat
! 417: program appeared in
! 418: .Bx 4.3 .
! 419: .Sh BUGS
! 420: Takes 2-10 percent of the cpu.
! 421: Certain displays presume a minimum of 80 characters per line.
! 422: The
! 423: .Ic vmstat
! 424: display looks out of place because it is (it was added in as
! 425: a separate display rather than created as a new program).