Annotation of src/usr.bin/systat/systat.1, Revision 1.16
1.16 ! aaron 1: .\" $OpenBSD: systat.1,v 1.15 2000/03/06 03:17:39 aaron 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.
15: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by the University of
18: .\" California, Berkeley and its contributors.
19: .\" 4. Neither the name of the University nor the names of its contributors
20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" @(#)systat.1 8.2 (Berkeley) 12/30/93
36: .\"
37: .Dd December 30, 1993
38: .Dt SYSTAT 1
1.12 aaron 39: .Os
1.1 deraadt 40: .Sh NAME
41: .Nm systat
42: .Nd display system statistics on a crt
43: .Sh SYNOPSIS
44: .Nm systat
1.2 deraadt 45: .Op Fl M Ar core
46: .Op Fl N Ar system
47: .Op Fl w Ar wait
48: .Op Ar display
1.1 deraadt 49: .Op Ar refresh-interval
50: .Sh DESCRIPTION
1.13 aaron 51: .Nm
1.1 deraadt 52: displays various system statistics in a screen oriented fashion
53: using the curses screen display library,
54: .Xr curses 3 .
55: .Pp
56: While
1.13 aaron 57: .Nm
1.1 deraadt 58: is running the screen is usually divided into two windows (an exception
1.16 ! aaron 59: is the vmstat display which uses the entire screen).
! 60: The upper window depicts the current system load average.
! 61: The information displayed in the lower window may vary, depending on
! 62: user commands.
! 63: The last line on the screen is reserved for user
1.1 deraadt 64: input and error messages.
65: .Pp
66: By default
1.13 aaron 67: .Nm
1.1 deraadt 68: displays the processes getting the largest percentage of the processor
1.16 ! aaron 69: in the lower window.
! 70: Other displays show swap space usage, disk
1.1 deraadt 71: .Tn I/O
72: statistics (a la
1.13 aaron 73: .Xr iostat 8 ) ,
1.1 deraadt 74: virtual memory statistics (a la
1.13 aaron 75: .Xr vmstat 8 ) ,
76: network
77: .Dq mbuf
78: utilization, and network connections (a la
79: .Xr netstat 1 ) .
1.1 deraadt 80: .Pp
81: Input is interpreted at two different levels.
1.13 aaron 82: A
83: .Dq global
84: command interpreter processes all keyboard input.
1.1 deraadt 85: If this command interpreter fails to recognize a command, the
1.16 ! aaron 86: input line is passed to a per-display command interpreter.
! 87: This allows each display to have certain display-specific commands.
1.1 deraadt 88: .Pp
1.16 ! aaron 89: The options are as follows:
1.1 deraadt 90: .Bl -tag -width "refresh_interval"
1.2 deraadt 91: .It Fl M Ar core
92: Extract values associated with the name list from
93: .Ar core
94: instead of the default
1.8 aaron 95: .Pa /dev/kmem .
1.2 deraadt 96: .It Fl N Ar system
1.6 d 97: Extract the name list from
1.2 deraadt 98: .Ar system
99: instead of the default
1.4 ccappuc 100: .Pa /bsd .
1.2 deraadt 101: .It Ar display
1.1 deraadt 102: The
103: .Ar display
1.2 deraadt 104: argument expects to be one of:
1.1 deraadt 105: .Ic pigs ,
106: .Ic iostat ,
107: .Ic swap ,
108: .Ic mbufs ,
109: .Ic vmstat
110: or
111: .Ic netstat .
1.2 deraadt 112: These displays can also be requested interactively and are described in
1.1 deraadt 113: full detail below.
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.2 deraadt 119: .Ar refresh-interval
120: specified with the
121: .Fl w
122: flag.
1.1 deraadt 123: .El
124: .Pp
125: Certain characters cause immediate action by
1.13 aaron 126: .Nm systat .
1.1 deraadt 127: These are
128: .Bl -tag -width Fl
129: .It Ic \&^L
130: Refresh the screen.
131: .It Ic \&^G
1.13 aaron 132: Print the name of the current
133: .Dq display
134: being shown in
1.1 deraadt 135: the lower window and the refresh interval.
136: .It Ic \&^Z
137: Stop
1.13 aaron 138: .Nm systat .
1.1 deraadt 139: .It Ic \&:
140: Move the cursor to the command line and interpret the input
1.16 ! aaron 141: line typed as a command.
! 142: While entering a command the
1.1 deraadt 143: current character erase, word erase, and line kill characters
144: may be used.
145: .El
146: .Pp
1.13 aaron 147: The following commands are interpreted by the
148: .Dq global
1.1 deraadt 149: command interpreter.
150: .Bl -tag -width Fl
151: .It Ic help
152: Print the names of the available displays on the command line.
153: .It Ic load
154: Print the load average over the past 1, 5, and 15 minutes
155: on the command line.
156: .It Ic stop
157: Stop refreshing the screen.
158: .It Xo
159: .Op Ic start
160: .Op Ar number
161: .Xc
1.16 ! aaron 162: Start (continue) refreshing the screen.
! 163: If a second, numeric,
1.1 deraadt 164: argument is provided it is interpreted as a refresh interval
165: (in seconds).
166: Supplying only a number will set the refresh interval to this
167: value.
168: .It Ic quit
169: Exit
1.13 aaron 170: .Nm systat .
1.1 deraadt 171: (This may be abbreviated to
1.13 aaron 172: .Ic q . )
1.1 deraadt 173: .El
174: .Pp
175: The available displays are:
176: .Bl -tag -width Ic
177: .It Ic pigs
178: Display, in the lower window, those processes resident in main
179: memory and getting the
180: largest portion of the processor (the default display).
181: When less than 100% of the
182: processor is scheduled to user processes, the remaining time
1.13 aaron 183: is accounted to the
184: .Dq idle
185: process.
1.1 deraadt 186: .It Ic iostat
187: Display, in the lower window, statistics about processor use
1.16 ! aaron 188: and disk throughput.
! 189: Statistics on processor use appear as
! 190: bar graphs of the amount of time executing in user mode
! 191: .Pq Dq user ,
! 192: in user mode running low priority processes
! 193: .Pq Dq nice ,
! 194: in system mode
! 195: .Pq Dq system ,
! 196: and idle
! 197: .Pq Dq idle .
! 198: Statistics
1.1 deraadt 199: on disk throughput show, for each drive, kilobytes of data transferred,
1.2 deraadt 200: number of disk transactions performed, and time spent in disk accesses
1.16 ! aaron 201: (in milliseconds).
! 202: This information may be displayed as
! 203: bar graphs or as rows of numbers which scroll downward.
! 204: Bar graphs are shown by default.
1.1 deraadt 205: .Pp
206: The following commands are specific to the
207: .Ic iostat
208: display; the minimum unambiguous prefix may be supplied.
209: .Pp
210: .Bl -tag -width Fl -compact
211: .It Cm numbers
212: Show the disk
1.12 aaron 213: .Tn I/O
1.16 ! aaron 214: statistics in numeric form.
! 215: Values are displayed in numeric columns which scroll downward.
1.1 deraadt 216: .It Cm bars
217: Show the disk
218: .Tn I/O
219: statistics in bar graph form (default).
1.2 deraadt 220: .It Cm secs
221: Toggle the display of time in disk activity (the default is to
222: not display time).
1.1 deraadt 223: .El
224: .It Ic swap
1.12 aaron 225: Show information about swap space usage on all the
1.1 deraadt 226: swap areas compiled into the kernel.
227: The first column is the device name of the partition.
228: The next column is the total space available in the partition.
1.12 aaron 229: The
1.1 deraadt 230: .Ar Used
231: column indicates the total blocks used so far;
232: the graph shows the percentage of space in use on each partition.
1.8 aaron 233: If there is more than one swap partition in use,
1.1 deraadt 234: a total line is also shown.
1.8 aaron 235: Areas known to the kernel but not in use are shown as not available.
1.1 deraadt 236: .It Ic mbufs
237: Display, in the lower window, the number of mbufs allocated
1.16 ! aaron 238: for particular uses, i.e., data, socket structures, etc.
1.1 deraadt 239: .It Ic vmstat
240: Take over the entire display and show a (rather crowded) compendium
241: of statistics related to virtual memory usage, process scheduling,
1.14 alex 242: device interrupts, system name translation caching, disk
1.1 deraadt 243: .Tn I/O
244: etc.
245: .Pp
246: The upper left quadrant of the screen shows the number
1.8 aaron 247: of users logged in and the load average over the last 1, 5,
248: and 15 minute intervals.
1.1 deraadt 249: Below this line are statistics on memory utilization.
250: The first row of the table reports memory usage only among
1.8 aaron 251: active processes, that is, processes that have run in the previous
1.1 deraadt 252: twenty seconds.
253: The second row reports on memory usage of all processes.
254: The first column reports on the number of physical pages
255: claimed by processes.
256: The second column reports the number of physical pages that
1.8 aaron 257: are devoted to read-only text pages.
1.1 deraadt 258: The third and fourth columns report the same two figures for
1.8 aaron 259: virtual pages, that is, the number of pages that would be
1.1 deraadt 260: needed if all processes had all of their pages.
1.8 aaron 261: Finally, the last column shows the number of physical pages
1.1 deraadt 262: on the free list.
263: .Pp
1.5 flipk 264: Below the memory display is a list of the average number of processes
1.13 aaron 265: (over the last refresh interval) that are runnable
266: .Pq Sq r ,
267: in page wait
268: .Pq Sq p ,
269: in disk wait other than paging
270: .Pq Sq d ,
271: sleeping
272: .Pq Sq s ,
273: and swapped out but desiring to run
274: .Pq Sq w .
1.1 deraadt 275: Below the queue length listing is a numerical listing and
276: a bar graph showing the amount of
1.16 ! aaron 277: system (shown as
! 278: .Ql = ) ,
! 279: user (shown as
! 280: .Ql > ) ,
! 281: nice (shown as
! 282: .Ql - ) ,
! 283: and idle time (shown as
! 284: .Ql \ ) .
1.1 deraadt 285: .Pp
1.12 aaron 286: To the right of the Proc display are statistics about
1.16 ! aaron 287: Context switches
! 288: .Pq Dq Csw ,
! 289: Traps
! 290: .Pq Dq Trp ,
! 291: Syscalls
! 292: .Pq Dq Sys ,
! 293: Interrupts
! 294: .Pq Dq Int ,
! 295: Soft interrupts
! 296: .Pq Dq Sof ,
! 297: and Faults
! 298: .Pq Dq Flt
1.7 deraadt 299: which have occurred during the last refresh interval.
1.5 flipk 300: .Pp
301: Below the CPU Usage graph are statistics on name translations.
1.1 deraadt 302: It lists the number of names translated in the previous interval,
303: the number and percentage of the translations that were
304: handled by the system wide name translation cache, and
305: the number and percentage of the translations that were
306: handled by the per process name translation cache.
307: .Pp
1.5 flipk 308: At the bottom left is the disk usage display.
309: It reports the number of seeks, transfers, number
310: of kilobyte blocks transferred per second averaged over the
311: refresh period of the display (by default, five seconds), and
312: the time spent in disk accesses.
313: .Pp
1.1 deraadt 314: Under the date in the upper right hand quadrant are statistics
315: on paging and swapping activity.
316: The first two columns report the average number of pages
317: brought in and out per second over the last refresh interval
318: due to page faults and the paging daemon.
319: The third and fourth columns report the average number of pages
320: brought in and out per second over the last refresh interval
321: due to swap requests initiated by the scheduler.
322: The first row of the display shows the average
1.8 aaron 323: number of disk transfers per second over the last refresh interval.
324: The second row of the display shows the average
1.1 deraadt 325: number of pages transferred per second over the last refresh interval.
326: .Pp
327: Running down the right hand side of the display is a breakdown
328: of the interrupts being handled by the system.
329: At the top of the list is the total interrupts per second
330: over the time interval.
331: The rest of the column breaks down the total on a device
332: by device basis.
333: Only devices that have interrupted at least once since boot time are shown.
1.5 flipk 334: .Pp
335: Below the SWAPPING display and slightly to the left of the Interrupts
336: display is a list of virtual memory statistics. The abbreviations are:
337: .Bl -tag -compact -width XXXXXX -offset indent
338: .It cow
339: copy-on-write faults
340: .It objlk
341: object cache lookups
342: .It objht
343: object cache hits
344: .It zfod
345: pages zero filled on demand
346: .It nzfod
347: number of zfod's created
348: .It %zfod
349: percentage of zfod's used
350: .It kern
351: number of pages in use by kernel
352: .It wire
353: number of pages wired down
354: .It act
355: number of pages active
356: .It inact
357: number of pages inactive
358: .It free
359: number of pages free
360: .It daefr
361: pages freed by daemon
362: .It prcfr
363: pages freed by exiting processes
364: .It react
365: number of pages reactivated from free list
366: .It scan
367: scans in page out daemon
368: .It hdrev
369: revolutions of the hand in page out daemon
370: .It intrn
371: intransit blocking page faults
372: .El
373: .Pp
1.13 aaron 374: The
375: .Ql %zfod
376: value is more interesting when observed over a long
1.5 flipk 377: period, such as from boot time (see the
378: .Cm boot
379: option below).
1.1 deraadt 380: .Pp
381: The following commands are specific to the
382: .Ic vmstat
383: display; the minimum unambiguous prefix may be supplied.
384: .Pp
1.16 ! aaron 385: .Bl -tag -width Ds -compact
1.1 deraadt 386: .It Cm boot
387: Display cumulative statistics since the system was booted.
388: .It Cm run
389: Display statistics as a running total from the point this
390: command is given.
391: .It Cm time
392: Display statistics averaged over the refresh interval (the default).
393: .It Cm zero
394: Reset running statistics to zero.
395: .El
396: .It Ic netstat
1.16 ! aaron 397: Display, in the lower window, network connections.
! 398: By default, network servers awaiting requests are not displayed.
! 399: Each address
! 400: is displayed in the format
! 401: .Dq host.port ,
! 402: with each shown symbolically, when possible.
! 403: It is possible to have addresses displayed numerically,
1.1 deraadt 404: limit the display to a set of ports, hosts, and/or protocols
405: (the minimum unambiguous prefix may be supplied):
1.16 ! aaron 406: .Bl -tag -width Ar
1.1 deraadt 407: .It Cm all
408: Toggle the displaying of server processes awaiting requests (this
409: is the equivalent of the
410: .Fl a
411: flag to
1.13 aaron 412: .Xr netstat 1 ) .
1.1 deraadt 413: .It Cm numbers
414: Display network addresses numerically.
415: .It Cm names
416: Display network addresses symbolically.
1.16 ! aaron 417: .It Cm protocol
1.1 deraadt 418: Display only network connections using the indicated protocol
1.13 aaron 419: (currently either
420: .Dq tcp
421: or
422: .Dq udp ) .
1.1 deraadt 423: .It Cm ignore Op Ar items
424: Do not display information about connections associated with
1.16 ! aaron 425: the specified hosts or ports.
! 426: Hosts and ports may be specified
! 427: by name
! 428: .Pf ( Dq vangogh ,
! 429: .Dq ftp ) ,
! 430: or numerically.
! 431: Host addresses
! 432: use the Internet dot notation
! 433: .Pq Dq 128.32.0.9 .
! 434: Multiple items
1.1 deraadt 435: may be specified with a single command by separating them with
436: spaces.
437: .It Cm display Op Ar items
438: Display information about the connections associated with the
1.16 ! aaron 439: specified hosts or ports.
! 440: As for
1.13 aaron 441: .Ar ignore ,
1.8 aaron 442: .Ar items
1.1 deraadt 443: may be names or numbers.
444: .It Cm show Op Ar ports\&|hosts
445: Show, on the command line, the currently selected protocols,
1.16 ! aaron 446: hosts, and ports.
! 447: Hosts and ports which are being ignored are prefixed with a
! 448: .Ql ! .
! 449: If
1.1 deraadt 450: .Ar ports
451: or
452: .Ar hosts
453: is supplied as an argument to
1.13 aaron 454: .Cm show ,
1.1 deraadt 455: then only the requested information will be displayed.
456: .It Cm reset
457: Reset the port, host, and protocol matching mechanisms to the default
458: (any protocol, port, or host).
459: .El
460: .El
461: .Pp
462: Commands to switch between displays may be abbreviated to the
1.16 ! aaron 463: minimum unambiguous prefix; for example,
! 464: .Dq io
! 465: for
! 466: .Dq iostat .
1.1 deraadt 467: Certain information may be discarded when the screen size is
1.16 ! aaron 468: insufficient for display.
! 469: For example, on a machine with 10 drives the
1.1 deraadt 470: .Ic iostat
1.16 ! aaron 471: bar graph displays only 3 drives on a 24 line terminal.
! 472: When a bar graph would overflow the allotted screen space it is
! 473: truncated and the actual value is printed
! 474: .Dq over top
! 475: of the bar.
1.1 deraadt 476: .Pp
477: The following commands are common to each display which shows
1.16 ! aaron 478: information about disk drives.
! 479: These commands are used to
1.1 deraadt 480: select a set of drives to report on, should your system have
481: more drives configured than can normally be displayed on the
482: screen.
483: .Pp
484: .Bl -tag -width Tx -compact
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: .It Cm display Op Ar drives
1.16 ! aaron 489: Display information about the drives indicated.
! 490: Multiple drives may be specified, separated by spaces.
1.1 deraadt 491: .El
492: .Sh FILES
493: .Bl -tag -width /etc/networks -compact
1.4 ccappuc 494: .It Pa /bsd
1.8 aaron 495: for the namelist
1.1 deraadt 496: .It Pa /dev/kmem
1.8 aaron 497: for information in main memory
1.1 deraadt 498: .It Pa /dev/drum
1.8 aaron 499: for information about swapped out processes
1.1 deraadt 500: .It Pa /etc/hosts
1.13 aaron 501: for host names
1.1 deraadt 502: .It Pa /etc/networks
1.8 aaron 503: for network names
1.1 deraadt 504: .It Pa /etc/services
1.13 aaron 505: for port names
1.1 deraadt 506: .El
1.15 aaron 507: .Sh SEE ALSO
508: .Xr kill 1 ,
509: .Xr ps 1 ,
510: .Xr top 1 ,
511: .Xr renice 8
1.1 deraadt 512: .Sh HISTORY
513: The
1.13 aaron 514: .Nm
1.1 deraadt 515: program appeared in
516: .Bx 4.3 .
517: .Sh BUGS
1.10 aaron 518: Takes 2-10 percent of the CPU.
1.1 deraadt 519: Certain displays presume a minimum of 80 characters per line.
520: The
521: .Ic vmstat
522: display looks out of place because it is (it was added in as
523: 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