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