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