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