Annotation of src/usr.bin/systat/systat.1, Revision 1.64
1.64 ! jmc 1: .\" $OpenBSD: systat.1,v 1.63 2008/08/08 21:48:19 sobrado 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: .\"
1.63 sobrado 33: .Dd $Mdocdate: August 8 2008 $
1.1 deraadt 34: .Dt SYSTAT 1
1.12 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm systat
1.41 jmc 38: .Nd display system statistics
1.1 deraadt 39: .Sh SYNOPSIS
40: .Nm systat
1.62 matthieu 41: .Op Fl abin
42: .Op Fl d Ar count
43: .Op Fl S Ar start
44: .Op Fl s Ar delay
45: .Op Fl w Ar width
46: .Op Ar view
47: .Op Ar delay
1.1 deraadt 48: .Sh DESCRIPTION
1.13 aaron 49: .Nm
1.1 deraadt 50: displays various system statistics in a screen oriented fashion
51: using the curses screen display library,
52: .Xr curses 3 .
53: .Pp
54: While
1.13 aaron 55: .Nm
1.1 deraadt 56: is running the screen is usually divided into two windows (an exception
1.16 aaron 57: is the vmstat display which uses the entire screen).
58: The upper window depicts the current system load average.
59: The information displayed in the lower window may vary, depending on
60: user commands.
61: The last line on the screen is reserved for user
1.1 deraadt 62: input and error messages.
63: .Pp
64: By default
1.13 aaron 65: .Nm
1.1 deraadt 66: displays the processes getting the largest percentage of the processor
1.16 aaron 67: in the lower window.
1.60 jmc 68: Other displays include swap space usage, disk I/O
1.1 deraadt 69: statistics (a la
1.13 aaron 70: .Xr iostat 8 ) ,
1.1 deraadt 71: virtual memory statistics (a la
1.13 aaron 72: .Xr vmstat 8 ) ,
73: network
74: .Dq mbuf
75: utilization, and network connections (a la
76: .Xr netstat 1 ) .
1.1 deraadt 77: .Pp
78: Input is interpreted at two different levels.
1.13 aaron 79: A
80: .Dq global
81: command interpreter processes all keyboard input.
1.1 deraadt 82: If this command interpreter fails to recognize a command, the
1.16 aaron 83: input line is passed to a per-display command interpreter.
84: This allows each display to have certain display-specific commands.
1.1 deraadt 85: .Pp
1.16 aaron 86: The options are as follows:
1.62 matthieu 87: .Bl -tag -width Ds
1.64 ! jmc 88: .It Fl a
1.62 matthieu 89: Display all lines.
90: .It Fl b
1.64 ! jmc 91: Raw, non interactive mode.
1.62 matthieu 92: .It Fl d Ar count
93: Exit after
94: .Ar count
95: screen updates.
96: .It Fl i
97: Interactive mode.
1.34 itojun 98: .It Fl n
99: Do not try to reverse-map IP address.
1.62 matthieu 100: .It Fl s Ar delay
1.31 jmc 101: Specifies the screen refresh time interval in seconds.
1.62 matthieu 102: This option is overridden by the final
1.64 ! jmc 103: .Ar delay
1.62 matthieu 104: argument if given.
1.31 jmc 105: The default interval is 5 seconds.
1.62 matthieu 106: .\".It Fl S Ar start
107: .\"??? no idea what that does
108: .It Fl w Ar width
1.63 sobrado 109: Specifies the maximum width of the display.
1.62 matthieu 110: .\" XXX not sure for the above.
111: .It Ar view
1.1 deraadt 112: The
1.62 matthieu 113: .Ar view
1.2 deraadt 114: argument expects to be one of:
1.62 matthieu 115: .Ic vmstat ,
1.1 deraadt 116: .Ic pigs ,
1.62 matthieu 117: .Ic ifstat ,
1.1 deraadt 118: .Ic iostat ,
1.49 deraadt 119: .Ic sensors ,
1.1 deraadt 120: .Ic mbufs ,
1.62 matthieu 121: .Ic netstat ,
122: .Ic swap ,
123: .Ic states ,
124: .Ic rules ,
125: .Ic queues
1.1 deraadt 126: or
1.62 matthieu 127: .Ic pf .
1.2 deraadt 128: These displays can also be requested interactively and are described in
1.1 deraadt 129: full detail below.
1.62 matthieu 130: .Ar view
1.53 jmc 131: may be abbreviated to the minimum unambiguous prefix;
132: for example,
1.50 jmc 133: .Dq io
134: for
135: .Dq iostat .
1.62 matthieu 136: .It Ar delay
1.1 deraadt 137: The
1.62 matthieu 138: .Ar delay
1.16 aaron 139: specifies the screen refresh time interval in seconds.
140: This is provided for backwards compatibility, and overrides the
1.31 jmc 141: .Ar wait
142: interval specified with the
1.2 deraadt 143: .Fl w
144: flag.
1.31 jmc 145: The default interval is 5 seconds.
1.1 deraadt 146: .El
147: .Pp
148: Certain characters cause immediate action by
1.61 jmc 149: .Nm .
1.63 sobrado 150: These are:
1.1 deraadt 151: .Bl -tag -width Fl
152: .It Ic \&^L
153: Refresh the screen.
154: .It Ic \&^G
1.13 aaron 155: Print the name of the current
156: .Dq display
157: being shown in
1.1 deraadt 158: the lower window and the refresh interval.
159: .It Ic \&^Z
1.27 jmc 160: Suspend
1.61 jmc 161: .Nm .
1.1 deraadt 162: .It Ic \&:
163: Move the cursor to the command line and interpret the input
1.16 aaron 164: line typed as a command.
165: While entering a command the
1.1 deraadt 166: current character erase, word erase, and line kill characters
167: may be used.
1.59 jmc 168: .It Ic q
169: Exit
170: .Nm .
1.1 deraadt 171: .El
172: .Pp
1.13 aaron 173: The following commands are interpreted by the
174: .Dq global
1.1 deraadt 175: command interpreter.
176: .Bl -tag -width Fl
177: .It Ic help
178: Print the names of the available displays on the command line.
179: .It Ic load
180: Print the load average over the past 1, 5, and 15 minutes
181: on the command line.
1.52 jmc 182: .It Ic quit
183: Exit
1.61 jmc 184: .Nm .
1.52 jmc 185: (This may be abbreviated to
186: .Ic q . )
1.1 deraadt 187: .It Ic stop
188: Stop refreshing the screen.
189: .It Xo
190: .Op Ic start
191: .Op Ar number
192: .Xc
1.16 aaron 193: Start (continue) refreshing the screen.
194: If a second, numeric,
1.1 deraadt 195: argument is provided it is interpreted as a refresh interval
196: (in seconds).
197: Supplying only a number will set the refresh interval to this
198: value.
199: .El
200: .Pp
1.53 jmc 201: Again,
202: .Ar display
203: may be abbreviated to the minimum unambiguous prefix.
1.1 deraadt 204: The available displays are:
1.52 jmc 205: .Bl -tag -width "netstatXXX"
206: .It Ic ifstat
207: Display, in the lower window, interface statistics.
208: The
209: .Dq State
210: column has the format
211: .Sm off
212: .Xo
213: .Cm up \*(Ba dn
214: .Bq : Cm U \*(Ba D .
215: .Xc
216: .Sm on
217: .Sq up
218: and
219: .Sq dn
220: represent whether the interface is up or down.
221: .Sq U
222: and
223: .Sq D
224: represent whether the interface is connected or not;
225: in the case of
226: .Xr carp 4
227: interfaces, whether the interface is in master or backup state, respectively.
228: See below for more options.
229: .It Ic iostat
230: Display, in the lower window, statistics about disk throughput.
231: Statistics
232: on disk throughput show, for each drive, data transferred in kilobytes,
233: number of disk transactions performed, and time spent in disk accesses
1.56 otto 234: (in fractions of a second).
1.52 jmc 235: .It Ic mbufs
236: Display, in the lower window, the number of mbufs allocated
237: for particular uses, i.e., data, socket structures, etc.
238: .It Ic netstat
239: Display, in the lower window, network connections.
240: By default, network servers awaiting requests are not displayed.
241: Each address
242: is displayed in the format
243: .Dq host.port ,
244: with each shown symbolically, when possible.
245: It is possible to have addresses displayed numerically,
246: limit the display to a set of ports, hosts, and/or protocols
247: (the minimum unambiguous prefix may be supplied):
248: .Bl -tag -width Ar
249: .It Cm all
250: Toggle the displaying of server processes awaiting requests (this
251: is the equivalent of the
252: .Fl a
253: flag to
254: .Xr netstat 1 ) .
255: .It Cm display Op Ar items
256: Display information about the connections associated with the
257: specified hosts or ports.
258: As for
259: .Ar ignore ,
260: .Ar items
261: may be names or numbers.
262: .It Cm ignore Op Ar items
263: Do not display information about connections associated with
264: the specified hosts or ports.
265: Hosts and ports may be specified
266: by name
267: .Pf ( Dq vangogh ,
268: .Dq ftp ) ,
269: or numerically.
270: Host addresses
271: use the Internet dot notation
272: .Pq Dq 128.32.0.9 .
273: Multiple items
274: may be specified with a single command by separating them with
275: spaces.
276: .It Cm names
277: Display network addresses symbolically.
278: .It Cm numbers
279: Display network addresses numerically.
280: .It Cm reset
281: Reset the port, host, and protocol matching mechanisms to the default
282: (any protocol, port, or host).
1.63 sobrado 283: .It Cm show Oo
284: .Ar protocols \*(Ba ports \*(Ba hosts
285: .Oc
1.52 jmc 286: Show, on the command line, the currently selected protocols,
287: hosts, and ports.
1.55 moritz 288: Protocols, hosts and ports which are being ignored are prefixed with a
1.52 jmc 289: .Ql \&! .
1.55 moritz 290: If an argument is supplied to
1.52 jmc 291: .Cm show ,
292: then only the requested information will be displayed.
1.55 moritz 293: .It Cm tcp \*(Ba udp \*(Ba all
294: Display only network connections using the indicated protocol.
1.52 jmc 295: .El
1.62 matthieu 296: .It Ic pf
1.64 ! jmc 297: Display filter information about
1.62 matthieu 298: .Xr pf 4 ,
299: similar to the output of
1.64 ! jmc 300: .Cm pfctl Fl s Cm info
1.62 matthieu 301: option.
1.1 deraadt 302: .It Ic pigs
303: Display, in the lower window, those processes resident in main
304: memory and getting the
305: largest portion of the processor (the default display).
306: When less than 100% of the
307: processor is scheduled to user processes, the remaining time
1.13 aaron 308: is accounted to the
309: .Dq idle
310: process.
1.62 matthieu 311: .It Ic queues
1.64 ! jmc 312: Display statistics about the active
! 313: .Xr altq 9
! 314: queues, similar to the output of
1.62 matthieu 315: .Cm pfctl Fl s Cm queue .
316: .It Ic rules
1.64 ! jmc 317: Display pf rules statistics, similar to the output of
1.62 matthieu 318: .Cm pfctl Fl s Cm rules .
1.52 jmc 319: .It Ic sensors
320: Display, in the lower window,
321: the current values of available hardware sensors,
322: in a format similar to that of
323: .Xr sysctl 8 .
1.62 matthieu 324: .It Ic states
1.64 ! jmc 325: Display pf states statistics, similar to the output of
1.62 matthieu 326: .Cm pfctl Fl s Cm states .
1.1 deraadt 327: .It Ic swap
1.12 aaron 328: Show information about swap space usage on all the
1.1 deraadt 329: swap areas compiled into the kernel.
330: The first column is the device name of the partition.
331: The next column is the total space available in the partition.
1.12 aaron 332: The
1.1 deraadt 333: .Ar Used
334: column indicates the total blocks used so far;
335: the graph shows the percentage of space in use on each partition.
1.8 aaron 336: If there is more than one swap partition in use,
1.1 deraadt 337: a total line is also shown.
1.8 aaron 338: Areas known to the kernel but not in use are shown as not available.
1.1 deraadt 339: .It Ic vmstat
340: Take over the entire display and show a (rather crowded) compendium
341: of statistics related to virtual memory usage, process scheduling,
1.60 jmc 342: device interrupts, system name translation caching, disk I/O etc.
1.1 deraadt 343: .Pp
344: The upper left quadrant of the screen shows the number
1.8 aaron 345: of users logged in and the load average over the last 1, 5,
346: and 15 minute intervals.
1.1 deraadt 347: Below this line are statistics on memory utilization.
348: The first row of the table reports memory usage only among
1.8 aaron 349: active processes, that is, processes that have run in the previous
1.1 deraadt 350: twenty seconds.
351: The second row reports on memory usage of all processes.
1.47 millert 352: The first column reports on the amount of physical memory
1.1 deraadt 353: claimed by processes.
1.29 jmc 354: The second column reports the same figure for
1.47 millert 355: virtual memory, that is, the amount of memory that would be
356: needed if all processes were resident at the same time.
357: Finally, the last column shows the amount of physical memory
1.1 deraadt 358: on the free list.
359: .Pp
1.5 flipk 360: Below the memory display is a list of the average number of processes
1.13 aaron 361: (over the last refresh interval) that are runnable
362: .Pq Sq r ,
363: in disk wait other than paging
364: .Pq Sq d ,
365: sleeping
366: .Pq Sq s ,
367: and swapped out but desiring to run
368: .Pq Sq w .
1.1 deraadt 369: Below the queue length listing is a numerical listing and
370: a bar graph showing the amount of
1.40 dlg 371: interrupt (shown as
1.63 sobrado 372: .Ql \*(Ba ) ,
1.16 aaron 373: system (shown as
374: .Ql = ) ,
375: user (shown as
1.43 jmc 376: .Ql \*(Gt ) ,
1.16 aaron 377: nice (shown as
378: .Ql - ) ,
379: and idle time (shown as
1.29 jmc 380: .Ql \ \& ) .
1.1 deraadt 381: .Pp
1.12 aaron 382: To the right of the Proc display are statistics about
1.16 aaron 383: Context switches
384: .Pq Dq Csw ,
385: Traps
386: .Pq Dq Trp ,
387: Syscalls
388: .Pq Dq Sys ,
389: Interrupts
390: .Pq Dq Int ,
391: Soft interrupts
392: .Pq Dq Sof ,
393: and Faults
394: .Pq Dq Flt
1.7 deraadt 395: which have occurred during the last refresh interval.
1.5 flipk 396: .Pp
397: Below the CPU Usage graph are statistics on name translations.
1.1 deraadt 398: It lists the number of names translated in the previous interval,
399: the number and percentage of the translations that were
400: handled by the system wide name translation cache, and
401: the number and percentage of the translations that were
402: handled by the per process name translation cache.
403: .Pp
1.5 flipk 404: At the bottom left is the disk usage display.
405: It reports the number of seeks, transfers, number
406: of kilobyte blocks transferred per second averaged over the
407: refresh period of the display (by default, five seconds), and
408: the time spent in disk accesses.
409: .Pp
1.1 deraadt 410: Under the date in the upper right hand quadrant are statistics
411: on paging and swapping activity.
412: The first two columns report the average number of pages
413: brought in and out per second over the last refresh interval
414: due to page faults and the paging daemon.
415: The third and fourth columns report the average number of pages
416: brought in and out per second over the last refresh interval
417: due to swap requests initiated by the scheduler.
418: The first row of the display shows the average
1.8 aaron 419: number of disk transfers per second over the last refresh interval.
420: The second row of the display shows the average
1.1 deraadt 421: number of pages transferred per second over the last refresh interval.
422: .Pp
423: Running down the right hand side of the display is a breakdown
424: of the interrupts being handled by the system.
425: At the top of the list is the total interrupts per second
426: over the time interval.
427: The rest of the column breaks down the total on a device
428: by device basis.
429: Only devices that have interrupted at least once since boot time are shown.
1.5 flipk 430: .Pp
431: Below the SWAPPING display and slightly to the left of the Interrupts
1.18 aaron 432: display is a list of virtual memory statistics.
433: The abbreviations are:
1.36 jmc 434: .Pp
1.38 niallo 435: .Bl -tag -compact -width "kmapentXX" -offset indent
1.21 deraadt 436: .It forks
437: process forks
438: .It fkppw
439: forks where parent waits
440: .It fksvm
441: forks where vmspace is shared
442: .It pwait
443: fault had to wait on a page
444: .It relck
445: fault relock called
446: .It rlkok
447: fault relock is successful
448: .It noram
449: faults out of ram
450: .It ndcpy
451: number of times fault clears "need copy"
452: .It fltcp
453: number of times fault promotes with copy
454: .It zfod
455: fault promotes with zerofill
1.5 flipk 456: .It cow
1.21 deraadt 457: number of times fault anon cow
458: .It fmin
459: min number of free pages
460: .It ftarg
461: target number of free pages
462: .It itarg
463: target number of inactive pages
464: .It wired
465: wired pages
1.25 deraadt 466: .It pdfre
1.21 deraadt 467: pages daemon freed since boot
468: .It pdscn
469: pages daemon scanned since boot
1.38 niallo 470: .It pzidle
471: number of zeroed pages
472: .It kmapent
473: number of kernel map entries
1.5 flipk 474: .El
475: .Pp
1.13 aaron 476: The
477: .Ql %zfod
478: value is more interesting when observed over a long
1.5 flipk 479: period, such as from boot time (see the
480: .Cm boot
481: option below).
1.35 markus 482: .El
483: .Pp
484: The following commands are specific to the
485: .Ic vmstat
486: and
487: .Ic ifstat
488: displays; the minimum unambiguous prefix may be supplied.
489: .Pp
490: .Bl -tag -width Ds -compact
491: .It Cm boot
492: Display cumulative statistics since the system was booted.
493: .It Cm run
494: Display statistics as a running total from the point this
495: command is given.
496: .It Cm time
497: Display statistics averaged over the refresh interval (the default).
498: .It Cm zero
499: Reset running statistics to zero.
1.1 deraadt 500: .El
501: .Pp
502: Certain information may be discarded when the screen size is
1.16 aaron 503: insufficient for display.
504: For example, on a machine with 10 drives the
1.1 deraadt 505: .Ic iostat
1.16 aaron 506: bar graph displays only 3 drives on a 24 line terminal.
507: When a bar graph would overflow the allotted screen space it is
508: truncated and the actual value is printed
509: .Dq over top
510: of the bar.
1.1 deraadt 511: .Pp
512: The following commands are common to each display which shows
1.16 aaron 513: information about disk drives.
514: These commands are used to
1.1 deraadt 515: select a set of drives to report on, should your system have
516: more drives configured than can normally be displayed on the
517: screen.
518: .Pp
519: .Bl -tag -width Tx -compact
1.54 jmc 520: .It Cm display Op Ar drives
521: Display information about the drives indicated.
522: Multiple drives may be specified, separated by spaces.
1.1 deraadt 523: .It Cm ignore Op Ar drives
1.16 aaron 524: Do not display information about the drives indicated.
525: Multiple drives may be specified, separated by spaces.
1.1 deraadt 526: .El
527: .Sh FILES
528: .Bl -tag -width /etc/networks -compact
529: .It Pa /etc/hosts
1.22 miod 530: host names
1.1 deraadt 531: .It Pa /etc/networks
1.22 miod 532: network names
1.62 matthieu 533: .It Pa /etc/pf.conf
534: pf and altq configuration
1.1 deraadt 535: .It Pa /etc/services
1.22 miod 536: port names
1.1 deraadt 537: .El
1.15 aaron 538: .Sh SEE ALSO
1.37 jmc 539: .Xt fstat 1 ,
1.15 aaron 540: .Xr kill 1 ,
1.37 jmc 541: .Xr netstat 1 ,
1.15 aaron 542: .Xr ps 1 ,
543: .Xr top 1 ,
1.37 jmc 544: .Xr iostat 8 ,
1.62 matthieu 545: .Xr pfctl 8 ,
1.37 jmc 546: .Xr pstat 8 ,
547: .Xr renice 8 ,
1.48 deanna 548: .Xr sysctl 8 ,
1.37 jmc 549: .Xr vmstat 8
1.1 deraadt 550: .Sh HISTORY
551: The
1.13 aaron 552: .Nm
1.1 deraadt 553: program appeared in
554: .Bx 4.3 .
555: .Sh BUGS
556: Certain displays presume a minimum of 80 characters per line.
557: The
558: .Ic vmstat
559: display looks out of place because it is (it was added in as
560: a separate display rather than created as a new program).
![[BACK]](/icons/back.gif){kind=icon}
Return to systat.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / systat