Annotation of src/usr.bin/systat/systat.1, Revision 1.18
1.18 ! aaron 1: .\" $OpenBSD: systat.1,v 1.17 2000/03/23 21:10:19 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
1.17 aaron 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
1.18 ! aaron 336: display is a list of virtual memory statistics.
! 337: The abbreviations are:
1.5 flipk 338: .Bl -tag -compact -width XXXXXX -offset indent
339: .It cow
340: copy-on-write faults
341: .It objlk
342: object cache lookups
343: .It objht
344: object cache hits
345: .It zfod
346: pages zero filled on demand
347: .It nzfod
348: number of zfod's created
349: .It %zfod
350: percentage of zfod's used
351: .It kern
352: number of pages in use by kernel
353: .It wire
354: number of pages wired down
355: .It act
356: number of pages active
357: .It inact
358: number of pages inactive
359: .It free
360: number of pages free
361: .It daefr
362: pages freed by daemon
363: .It prcfr
364: pages freed by exiting processes
365: .It react
366: number of pages reactivated from free list
367: .It scan
368: scans in page out daemon
369: .It hdrev
370: revolutions of the hand in page out daemon
371: .It intrn
372: intransit blocking page faults
373: .El
374: .Pp
1.13 aaron 375: The
376: .Ql %zfod
377: value is more interesting when observed over a long
1.5 flipk 378: period, such as from boot time (see the
379: .Cm boot
380: option below).
1.1 deraadt 381: .Pp
382: The following commands are specific to the
383: .Ic vmstat
384: display; the minimum unambiguous prefix may be supplied.
385: .Pp
1.16 aaron 386: .Bl -tag -width Ds -compact
1.1 deraadt 387: .It Cm boot
388: Display cumulative statistics since the system was booted.
389: .It Cm run
390: Display statistics as a running total from the point this
391: command is given.
392: .It Cm time
393: Display statistics averaged over the refresh interval (the default).
394: .It Cm zero
395: Reset running statistics to zero.
396: .El
397: .It Ic netstat
1.16 aaron 398: Display, in the lower window, network connections.
399: By default, network servers awaiting requests are not displayed.
400: Each address
401: is displayed in the format
402: .Dq host.port ,
403: with each shown symbolically, when possible.
404: It is possible to have addresses displayed numerically,
1.1 deraadt 405: limit the display to a set of ports, hosts, and/or protocols
406: (the minimum unambiguous prefix may be supplied):
1.16 aaron 407: .Bl -tag -width Ar
1.1 deraadt 408: .It Cm all
409: Toggle the displaying of server processes awaiting requests (this
410: is the equivalent of the
411: .Fl a
412: flag to
1.13 aaron 413: .Xr netstat 1 ) .
1.1 deraadt 414: .It Cm numbers
415: Display network addresses numerically.
416: .It Cm names
417: Display network addresses symbolically.
1.16 aaron 418: .It Cm protocol
1.1 deraadt 419: Display only network connections using the indicated protocol
1.13 aaron 420: (currently either
421: .Dq tcp
422: or
423: .Dq udp ) .
1.1 deraadt 424: .It Cm ignore Op Ar items
425: Do not display information about connections associated with
1.16 aaron 426: the specified hosts or ports.
427: Hosts and ports may be specified
428: by name
429: .Pf ( Dq vangogh ,
430: .Dq ftp ) ,
431: or numerically.
432: Host addresses
433: use the Internet dot notation
434: .Pq Dq 128.32.0.9 .
435: Multiple items
1.1 deraadt 436: may be specified with a single command by separating them with
437: spaces.
438: .It Cm display Op Ar items
439: Display information about the connections associated with the
1.16 aaron 440: specified hosts or ports.
441: As for
1.13 aaron 442: .Ar ignore ,
1.8 aaron 443: .Ar items
1.1 deraadt 444: may be names or numbers.
445: .It Cm show Op Ar ports\&|hosts
446: Show, on the command line, the currently selected protocols,
1.16 aaron 447: hosts, and ports.
448: Hosts and ports which are being ignored are prefixed with a
449: .Ql ! .
450: If
1.1 deraadt 451: .Ar ports
452: or
453: .Ar hosts
454: is supplied as an argument to
1.13 aaron 455: .Cm show ,
1.1 deraadt 456: then only the requested information will be displayed.
457: .It Cm reset
458: Reset the port, host, and protocol matching mechanisms to the default
459: (any protocol, port, or host).
460: .El
461: .El
462: .Pp
463: Commands to switch between displays may be abbreviated to the
1.16 aaron 464: minimum unambiguous prefix; for example,
465: .Dq io
466: for
467: .Dq iostat .
1.1 deraadt 468: Certain information may be discarded when the screen size is
1.16 aaron 469: insufficient for display.
470: For example, on a machine with 10 drives the
1.1 deraadt 471: .Ic iostat
1.16 aaron 472: bar graph displays only 3 drives on a 24 line terminal.
473: When a bar graph would overflow the allotted screen space it is
474: truncated and the actual value is printed
475: .Dq over top
476: of the bar.
1.1 deraadt 477: .Pp
478: The following commands are common to each display which shows
1.16 aaron 479: information about disk drives.
480: These commands are used to
1.1 deraadt 481: select a set of drives to report on, should your system have
482: more drives configured than can normally be displayed on the
483: screen.
484: .Pp
485: .Bl -tag -width Tx -compact
486: .It Cm ignore Op Ar drives
1.16 aaron 487: Do not display information about the drives indicated.
488: Multiple drives may be specified, separated by spaces.
1.1 deraadt 489: .It Cm display Op Ar drives
1.16 aaron 490: Display information about the drives indicated.
491: Multiple drives may be specified, separated by spaces.
1.1 deraadt 492: .El
493: .Sh FILES
494: .Bl -tag -width /etc/networks -compact
1.4 ccappuc 495: .It Pa /bsd
1.8 aaron 496: for the namelist
1.1 deraadt 497: .It Pa /dev/kmem
1.8 aaron 498: for information in main memory
1.1 deraadt 499: .It Pa /dev/drum
1.8 aaron 500: for information about swapped out processes
1.1 deraadt 501: .It Pa /etc/hosts
1.13 aaron 502: for host names
1.1 deraadt 503: .It Pa /etc/networks
1.8 aaron 504: for network names
1.1 deraadt 505: .It Pa /etc/services
1.13 aaron 506: for port names
1.1 deraadt 507: .El
1.15 aaron 508: .Sh SEE ALSO
509: .Xr kill 1 ,
510: .Xr ps 1 ,
511: .Xr top 1 ,
512: .Xr renice 8
1.1 deraadt 513: .Sh HISTORY
514: The
1.13 aaron 515: .Nm
1.1 deraadt 516: program appeared in
517: .Bx 4.3 .
518: .Sh BUGS
1.10 aaron 519: Takes 2-10 percent of the CPU.
1.1 deraadt 520: Certain displays presume a minimum of 80 characters per line.
521: The
522: .Ic vmstat
523: display looks out of place because it is (it was added in as
524: 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