Annotation of src/usr.bin/systat/systat.1, Revision 1.40
1.40 ! dlg 1: .\" $OpenBSD: systat.1,v 1.39 2006/01/16 10:26:13 jmc Exp $
1.2 deraadt 2: .\" $NetBSD: systat.1,v 1.6 1996/05/10 23:16:39 thorpej Exp $
1.1 deraadt 3: .\"
4: .\" Copyright (c) 1985, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.28 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)systat.1 8.2 (Berkeley) 12/30/93
32: .\"
33: .Dd December 30, 1993
34: .Dt SYSTAT 1
1.12 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm systat
1.33 jmc 38: .Nd display system statistics on a CRT
1.1 deraadt 39: .Sh SYNOPSIS
40: .Nm systat
1.34 itojun 41: .Op Fl n
1.2 deraadt 42: .Op Fl w Ar wait
43: .Op Ar display
1.1 deraadt 44: .Op Ar refresh-interval
45: .Sh DESCRIPTION
1.13 aaron 46: .Nm
1.1 deraadt 47: displays various system statistics in a screen oriented fashion
48: using the curses screen display library,
49: .Xr curses 3 .
50: .Pp
51: While
1.13 aaron 52: .Nm
1.1 deraadt 53: is running the screen is usually divided into two windows (an exception
1.16 aaron 54: is the vmstat display which uses the entire screen).
55: The upper window depicts the current system load average.
56: The information displayed in the lower window may vary, depending on
57: user commands.
58: The last line on the screen is reserved for user
1.1 deraadt 59: input and error messages.
60: .Pp
61: By default
1.13 aaron 62: .Nm
1.1 deraadt 63: displays the processes getting the largest percentage of the processor
1.16 aaron 64: in the lower window.
65: Other displays show swap space usage, disk
1.1 deraadt 66: .Tn I/O
67: statistics (a la
1.13 aaron 68: .Xr iostat 8 ) ,
1.1 deraadt 69: virtual memory statistics (a la
1.13 aaron 70: .Xr vmstat 8 ) ,
71: network
72: .Dq mbuf
73: utilization, and network connections (a la
74: .Xr netstat 1 ) .
1.1 deraadt 75: .Pp
76: Input is interpreted at two different levels.
1.13 aaron 77: A
78: .Dq global
79: command interpreter processes all keyboard input.
1.1 deraadt 80: If this command interpreter fails to recognize a command, the
1.16 aaron 81: input line is passed to a per-display command interpreter.
82: This allows each display to have certain display-specific commands.
1.1 deraadt 83: .Pp
1.16 aaron 84: The options are as follows:
1.31 jmc 85: .Bl -tag -width "refresh-interval"
1.34 itojun 86: .It Fl n
87: Do not try to reverse-map IP address.
1.31 jmc 88: .It Fl w Ar wait
89: Specifies the screen refresh time interval in seconds.
90: This option is overridden by
91: .Ar refresh-interval ,
92: if given.
93: The default interval is 5 seconds.
1.2 deraadt 94: .It Ar display
1.1 deraadt 95: The
96: .Ar display
1.2 deraadt 97: argument expects to be one of:
1.1 deraadt 98: .Ic pigs ,
99: .Ic iostat ,
100: .Ic swap ,
101: .Ic mbufs ,
1.35 markus 102: .Ic vmstat ,
103: .Ic ifstat
1.1 deraadt 104: or
105: .Ic netstat .
1.2 deraadt 106: These displays can also be requested interactively and are described in
1.1 deraadt 107: full detail below.
108: .It Ar refresh-interval
109: The
1.2 deraadt 110: .Ar refresh-interval
1.16 aaron 111: specifies the screen refresh time interval in seconds.
112: This is provided for backwards compatibility, and overrides the
1.31 jmc 113: .Ar wait
114: interval specified with the
1.2 deraadt 115: .Fl w
116: flag.
1.31 jmc 117: The default interval is 5 seconds.
1.1 deraadt 118: .El
119: .Pp
120: Certain characters cause immediate action by
1.13 aaron 121: .Nm systat .
1.1 deraadt 122: These are
123: .Bl -tag -width Fl
124: .It Ic \&^L
125: Refresh the screen.
126: .It Ic \&^G
1.13 aaron 127: Print the name of the current
128: .Dq display
129: being shown in
1.1 deraadt 130: the lower window and the refresh interval.
131: .It Ic \&^Z
1.27 jmc 132: Suspend
1.13 aaron 133: .Nm systat .
1.1 deraadt 134: .It Ic \&:
135: Move the cursor to the command line and interpret the input
1.16 aaron 136: line typed as a command.
137: While entering a command the
1.1 deraadt 138: current character erase, word erase, and line kill characters
139: may be used.
140: .El
141: .Pp
1.13 aaron 142: The following commands are interpreted by the
143: .Dq global
1.1 deraadt 144: command interpreter.
145: .Bl -tag -width Fl
146: .It Ic help
147: Print the names of the available displays on the command line.
148: .It Ic load
149: Print the load average over the past 1, 5, and 15 minutes
150: on the command line.
151: .It Ic stop
152: Stop refreshing the screen.
153: .It Xo
154: .Op Ic start
155: .Op Ar number
156: .Xc
1.16 aaron 157: Start (continue) refreshing the screen.
158: If a second, numeric,
1.1 deraadt 159: argument is provided it is interpreted as a refresh interval
160: (in seconds).
161: Supplying only a number will set the refresh interval to this
162: value.
163: .It Ic quit
164: Exit
1.13 aaron 165: .Nm systat .
1.1 deraadt 166: (This may be abbreviated to
1.13 aaron 167: .Ic q . )
1.1 deraadt 168: .El
169: .Pp
170: The available displays are:
171: .Bl -tag -width Ic
172: .It Ic pigs
173: Display, in the lower window, those processes resident in main
174: memory and getting the
175: largest portion of the processor (the default display).
176: When less than 100% of the
177: processor is scheduled to user processes, the remaining time
1.13 aaron 178: is accounted to the
179: .Dq idle
180: process.
1.1 deraadt 181: .It Ic iostat
182: Display, in the lower window, statistics about processor use
1.16 aaron 183: and disk throughput.
184: Statistics on processor use appear as
185: bar graphs of the amount of time executing in user mode
186: .Pq Dq user ,
187: in user mode running low priority processes
188: .Pq Dq nice ,
189: in system mode
190: .Pq Dq system ,
191: and idle
192: .Pq Dq idle .
193: Statistics
1.1 deraadt 194: on disk throughput show, for each drive, kilobytes of data transferred,
1.2 deraadt 195: number of disk transactions performed, and time spent in disk accesses
1.16 aaron 196: (in milliseconds).
197: This information may be displayed as
198: bar graphs or as rows of numbers which scroll downward.
199: Bar graphs are shown by default.
1.1 deraadt 200: .Pp
201: The following commands are specific to the
202: .Ic iostat
203: display; the minimum unambiguous prefix may be supplied.
204: .Pp
205: .Bl -tag -width Fl -compact
206: .It Cm numbers
207: Show the disk
1.12 aaron 208: .Tn I/O
1.16 aaron 209: statistics in numeric form.
210: Values are displayed in numeric columns which scroll downward.
1.1 deraadt 211: .It Cm bars
212: Show the disk
213: .Tn I/O
214: statistics in bar graph form (default).
1.2 deraadt 215: .It Cm secs
216: Toggle the display of time in disk activity (the default is to
217: not display time).
1.32 tedu 218: .It Cm split
219: Toggle the display of separate read/write statistics (the default is
220: combined statistics).
1.1 deraadt 221: .El
222: .It Ic swap
1.12 aaron 223: Show information about swap space usage on all the
1.1 deraadt 224: swap areas compiled into the kernel.
225: The first column is the device name of the partition.
226: The next column is the total space available in the partition.
1.12 aaron 227: The
1.1 deraadt 228: .Ar Used
229: column indicates the total blocks used so far;
230: the graph shows the percentage of space in use on each partition.
1.8 aaron 231: If there is more than one swap partition in use,
1.1 deraadt 232: a total line is also shown.
1.8 aaron 233: Areas known to the kernel but not in use are shown as not available.
1.1 deraadt 234: .It Ic mbufs
235: Display, in the lower window, the number of mbufs allocated
1.16 aaron 236: for particular uses, i.e., data, socket structures, etc.
1.1 deraadt 237: .It Ic vmstat
238: Take over the entire display and show a (rather crowded) compendium
239: of statistics related to virtual memory usage, process scheduling,
1.14 alex 240: device interrupts, system name translation caching, disk
1.1 deraadt 241: .Tn I/O
242: etc.
243: .Pp
244: The upper left quadrant of the screen shows the number
1.8 aaron 245: of users logged in and the load average over the last 1, 5,
246: and 15 minute intervals.
1.1 deraadt 247: Below this line are statistics on memory utilization.
248: The first row of the table reports memory usage only among
1.8 aaron 249: active processes, that is, processes that have run in the previous
1.1 deraadt 250: twenty seconds.
251: The second row reports on memory usage of all processes.
252: The first column reports on the number of physical pages
253: claimed by processes.
1.29 jmc 254: The second column reports the same figure for
1.8 aaron 255: virtual pages, that is, the number of pages that would be
1.1 deraadt 256: needed if all processes had all of their pages.
1.8 aaron 257: Finally, the last column shows the number of physical pages
1.1 deraadt 258: on the free list.
259: .Pp
1.5 flipk 260: Below the memory display is a list of the average number of processes
1.13 aaron 261: (over the last refresh interval) that are runnable
262: .Pq Sq r ,
263: in disk wait other than paging
264: .Pq Sq d ,
265: sleeping
266: .Pq Sq s ,
267: and swapped out but desiring to run
268: .Pq Sq w .
1.1 deraadt 269: Below the queue length listing is a numerical listing and
270: a bar graph showing the amount of
1.40 ! dlg 271: interrupt (shown as
! 272: .Ql | ) ,
1.16 aaron 273: system (shown as
274: .Ql = ) ,
275: user (shown as
276: .Ql > ) ,
277: nice (shown as
278: .Ql - ) ,
279: and idle time (shown as
1.29 jmc 280: .Ql \ \& ) .
1.1 deraadt 281: .Pp
1.12 aaron 282: To the right of the Proc display are statistics about
1.16 aaron 283: Context switches
284: .Pq Dq Csw ,
285: Traps
286: .Pq Dq Trp ,
287: Syscalls
288: .Pq Dq Sys ,
289: Interrupts
290: .Pq Dq Int ,
291: Soft interrupts
292: .Pq Dq Sof ,
293: and Faults
294: .Pq Dq Flt
1.7 deraadt 295: which have occurred during the last refresh interval.
1.5 flipk 296: .Pp
297: Below the CPU Usage graph are statistics on name translations.
1.1 deraadt 298: It lists the number of names translated in the previous interval,
299: the number and percentage of the translations that were
300: handled by the system wide name translation cache, and
301: the number and percentage of the translations that were
302: handled by the per process name translation cache.
303: .Pp
1.5 flipk 304: At the bottom left is the disk usage display.
305: It reports the number of seeks, transfers, number
306: of kilobyte blocks transferred per second averaged over the
307: refresh period of the display (by default, five seconds), and
308: the time spent in disk accesses.
309: .Pp
1.1 deraadt 310: Under the date in the upper right hand quadrant are statistics
311: on paging and swapping activity.
312: The first two columns report the average number of pages
313: brought in and out per second over the last refresh interval
314: due to page faults and the paging daemon.
315: The third and fourth columns report the average number of pages
316: brought in and out per second over the last refresh interval
317: due to swap requests initiated by the scheduler.
318: The first row of the display shows the average
1.8 aaron 319: number of disk transfers per second over the last refresh interval.
320: The second row of the display shows the average
1.1 deraadt 321: number of pages transferred per second over the last refresh interval.
322: .Pp
323: Running down the right hand side of the display is a breakdown
324: of the interrupts being handled by the system.
325: At the top of the list is the total interrupts per second
326: over the time interval.
327: The rest of the column breaks down the total on a device
328: by device basis.
329: Only devices that have interrupted at least once since boot time are shown.
1.5 flipk 330: .Pp
331: Below the SWAPPING display and slightly to the left of the Interrupts
1.18 aaron 332: display is a list of virtual memory statistics.
333: The abbreviations are:
1.36 jmc 334: .Pp
1.38 niallo 335: .Bl -tag -compact -width "kmapentXX" -offset indent
1.21 deraadt 336: .It forks
337: process forks
338: .It fkppw
339: forks where parent waits
340: .It fksvm
341: forks where vmspace is shared
342: .It pwait
343: fault had to wait on a page
344: .It relck
345: fault relock called
346: .It rlkok
347: fault relock is successful
348: .It noram
349: faults out of ram
350: .It ndcpy
351: number of times fault clears "need copy"
352: .It fltcp
353: number of times fault promotes with copy
354: .It zfod
355: fault promotes with zerofill
1.5 flipk 356: .It cow
1.21 deraadt 357: number of times fault anon cow
358: .It fmin
359: min number of free pages
360: .It ftarg
361: target number of free pages
362: .It itarg
363: target number of inactive pages
364: .It wired
365: wired pages
1.25 deraadt 366: .It pdfre
1.21 deraadt 367: pages daemon freed since boot
368: .It pdscn
369: pages daemon scanned since boot
1.38 niallo 370: .It pzidle
371: number of zeroed pages
372: .It kmapent
373: number of kernel map entries
1.5 flipk 374: .El
375: .Pp
1.13 aaron 376: The
377: .Ql %zfod
378: value is more interesting when observed over a long
1.5 flipk 379: period, such as from boot time (see the
380: .Cm boot
381: option below).
1.35 markus 382: .It Ic ifstat
383: Display, in the lower window, interface statistics.
384: See below for more options.
1.1 deraadt 385: .It Ic netstat
1.16 aaron 386: Display, in the lower window, network connections.
387: By default, network servers awaiting requests are not displayed.
388: Each address
389: is displayed in the format
390: .Dq host.port ,
391: with each shown symbolically, when possible.
392: It is possible to have addresses displayed numerically,
1.1 deraadt 393: limit the display to a set of ports, hosts, and/or protocols
394: (the minimum unambiguous prefix may be supplied):
1.16 aaron 395: .Bl -tag -width Ar
1.1 deraadt 396: .It Cm all
397: Toggle the displaying of server processes awaiting requests (this
398: is the equivalent of the
399: .Fl a
400: flag to
1.13 aaron 401: .Xr netstat 1 ) .
1.1 deraadt 402: .It Cm numbers
403: Display network addresses numerically.
404: .It Cm names
405: Display network addresses symbolically.
1.16 aaron 406: .It Cm protocol
1.1 deraadt 407: Display only network connections using the indicated protocol
1.13 aaron 408: (currently either
409: .Dq tcp
410: or
411: .Dq udp ) .
1.1 deraadt 412: .It Cm ignore Op Ar items
413: Do not display information about connections associated with
1.16 aaron 414: the specified hosts or ports.
415: Hosts and ports may be specified
416: by name
417: .Pf ( Dq vangogh ,
418: .Dq ftp ) ,
419: or numerically.
420: Host addresses
421: use the Internet dot notation
422: .Pq Dq 128.32.0.9 .
423: Multiple items
1.1 deraadt 424: may be specified with a single command by separating them with
425: spaces.
426: .It Cm display Op Ar items
427: Display information about the connections associated with the
1.16 aaron 428: specified hosts or ports.
429: As for
1.13 aaron 430: .Ar ignore ,
1.8 aaron 431: .Ar items
1.1 deraadt 432: may be names or numbers.
433: .It Cm show Op Ar ports\&|hosts
434: Show, on the command line, the currently selected protocols,
1.16 aaron 435: hosts, and ports.
436: Hosts and ports which are being ignored are prefixed with a
1.30 jmc 437: .Ql \&! .
1.16 aaron 438: If
1.1 deraadt 439: .Ar ports
440: or
441: .Ar hosts
442: is supplied as an argument to
1.13 aaron 443: .Cm show ,
1.1 deraadt 444: then only the requested information will be displayed.
445: .It Cm reset
446: Reset the port, host, and protocol matching mechanisms to the default
447: (any protocol, port, or host).
448: .El
1.35 markus 449: .El
450: .Pp
451: The following commands are specific to the
452: .Ic vmstat
453: and
454: .Ic ifstat
455: displays; the minimum unambiguous prefix may be supplied.
456: .Pp
457: .Bl -tag -width Ds -compact
458: .It Cm boot
459: Display cumulative statistics since the system was booted.
460: .It Cm run
461: Display statistics as a running total from the point this
462: command is given.
463: .It Cm time
464: Display statistics averaged over the refresh interval (the default).
465: .It Cm zero
466: Reset running statistics to zero.
1.1 deraadt 467: .El
468: .Pp
469: Commands to switch between displays may be abbreviated to the
1.16 aaron 470: minimum unambiguous prefix; for example,
471: .Dq io
472: for
473: .Dq iostat .
1.1 deraadt 474: Certain information may be discarded when the screen size is
1.16 aaron 475: insufficient for display.
476: For example, on a machine with 10 drives the
1.1 deraadt 477: .Ic iostat
1.16 aaron 478: bar graph displays only 3 drives on a 24 line terminal.
479: When a bar graph would overflow the allotted screen space it is
480: truncated and the actual value is printed
481: .Dq over top
482: of the bar.
1.1 deraadt 483: .Pp
484: The following commands are common to each display which shows
1.16 aaron 485: information about disk drives.
486: These commands are used to
1.1 deraadt 487: select a set of drives to report on, should your system have
488: more drives configured than can normally be displayed on the
489: screen.
490: .Pp
491: .Bl -tag -width Tx -compact
492: .It Cm ignore Op Ar drives
1.16 aaron 493: Do not display information about the drives indicated.
494: Multiple drives may be specified, separated by spaces.
1.1 deraadt 495: .It Cm display Op Ar drives
1.16 aaron 496: Display information about the drives indicated.
497: Multiple drives may be specified, separated by spaces.
1.1 deraadt 498: .El
499: .Sh FILES
500: .Bl -tag -width /etc/networks -compact
501: .It Pa /etc/hosts
1.22 miod 502: host names
1.1 deraadt 503: .It Pa /etc/networks
1.22 miod 504: network names
1.1 deraadt 505: .It Pa /etc/services
1.22 miod 506: port names
1.1 deraadt 507: .El
1.15 aaron 508: .Sh SEE ALSO
1.37 jmc 509: .Xt fstat 1 ,
1.15 aaron 510: .Xr kill 1 ,
1.37 jmc 511: .Xr netstat 1 ,
1.15 aaron 512: .Xr ps 1 ,
513: .Xr top 1 ,
1.37 jmc 514: .Xr iostat 8 ,
515: .Xr pstat 8 ,
516: .Xr renice 8 ,
517: .Xr vmstat 8
1.1 deraadt 518: .Sh HISTORY
519: The
1.13 aaron 520: .Nm
1.1 deraadt 521: program appeared in
522: .Bx 4.3 .
523: .Sh BUGS
1.10 aaron 524: Takes 2-10 percent of the CPU.
1.1 deraadt 525: Certain displays presume a minimum of 80 characters per line.
526: The
527: .Ic vmstat
528: display looks out of place because it is (it was added in as
529: a separate display rather than created as a new program).