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