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