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