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