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