Annotation of src/usr.bin/systat/systat.1, Revision 1.3
1.3 ! deraadt 1: .\" $OpenBSD: systat.1,v 1.6 1996/05/10 23:16:39 thorpej 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
51: .Nm Systat
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
89: .Pa /dev/mem .
90: .It Fl N Ar system
91: Extracr the name list from
92: .Ar system
93: instead of the default
94: .Pa /netbsd .
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
183: graphs are shown by default;
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.
212: If there are more than one swap partition in use,
213: a total line is also shown.
214: Areas known to the kernel, but not in use are shown as not available.
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
226: of users logged in and the load average over the last one, five,
227: and fifteen minute intervals.
228: Below this line are statistics on memory utilization.
229: The first row of the table reports memory usage only among
230: active processes, that is processes that have run in the previous
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
236: are devoted to read only text pages.
237: The third and fourth columns report the same two figures for
238: virtual pages, that is the number of pages that would be
239: needed if all processes had all of their pages.
240: Finally the last column shows the number of physical pages
241: on the free list.
242: .Pp
243: Below the memory display is the disk usage display.
1.2 deraadt 244: It reports the number of seeks, transfers, number
1.1 deraadt 245: of kilobyte blocks transferred per second averaged over the
1.2 deraadt 246: refresh period of the display (by default, five seconds), and
247: the time spent in disk accesses.
1.1 deraadt 248: Note that the system only keeps statistics on at most four disks.
249: .Pp
250: Below the disk display is a list of the
251: average number of processes (over the last refresh interval)
252: that are runnable (`r'), in page wait (`p'),
253: in disk wait other than paging (`d'),
254: sleeping (`s'), and swapped out but desiring to run (`w').
255: Below the queue length listing is a numerical listing and
256: a bar graph showing the amount of
257: system (shown as `='), user (shown as `>'),
258: nice (shown as `-'), and idle time (shown as ` ').
259: .Pp
260: At the bottom left are statistics on name translations.
261: It lists the number of names translated in the previous interval,
262: the number and percentage of the translations that were
263: handled by the system wide name translation cache, and
264: the number and percentage of the translations that were
265: handled by the per process name translation cache.
266: .Pp
267: Under the date in the upper right hand quadrant are statistics
268: on paging and swapping activity.
269: The first two columns report the average number of pages
270: brought in and out per second over the last refresh interval
271: due to page faults and the paging daemon.
272: The third and fourth columns report the average number of pages
273: brought in and out per second over the last refresh interval
274: due to swap requests initiated by the scheduler.
275: The first row of the display shows the average
276: number of disk transfers per second over the last refresh interval;
277: the second row of the display shows the average
278: number of pages transferred per second over the last refresh interval.
279: .Pp
280: Below the paging statistics is a line listing the average number of
281: total reclaims ('Rec'),
282: intransit blocking page faults (`It'),
283: swap text pages found in free list (`F/S'),
284: file system text pages found in free list (`F/F'),
285: reclaims from free list
286: pages freed by the clock daemon (`Fre'),
287: and sequential process pages freed (`SFr')
288: per second over the refresh interval.
289: .Pp
290: Below this line are statistics on the average number of
291: zero filled pages (`zf') and demand filled text pages (`xf')
292: per second over the refresh period.
293: The first row indicates the number of requests that were
294: resolved, the second row shows the number that were set up,
295: and the last row shows the percentage of setup requests that were
296: actually used.
297: Note that this percentage is usually less than 100%,
298: however it may exceed 100% if a large number of requests
299: are actually used long after they were set up during a
300: period when no new pages are being set up.
301: Thus this figure is most interesting when observed over
302: a long time period, such as from boot time
303: (see below on getting such a display).
304: .Pp
305: Below the page fill statistics is a column that
306: lists the average number of context switches (`Csw'),
307: traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'),
308: characters output to DZ ports using
309: .No pseudo Ns -DMA
310: (`Pdm'),
311: network software interrupts (`Sof'),
312: page faults (`Flt'), pages scanned by the page daemon (`Scn'),
313: and revolutions of the page daemon's hand (`Rev')
314: per second over the refresh interval.
315: .Pp
316: Running down the right hand side of the display is a breakdown
317: of the interrupts being handled by the system.
318: At the top of the list is the total interrupts per second
319: over the time interval.
320: The rest of the column breaks down the total on a device
321: by device basis.
322: Only devices that have interrupted at least once since boot time are shown.
323: .Pp
324: The following commands are specific to the
325: .Ic vmstat
326: display; the minimum unambiguous prefix may be supplied.
327: .Pp
328: .Bl -tag -width Ar -compact
329: .It Cm boot
330: Display cumulative statistics since the system was booted.
331: .It Cm run
332: Display statistics as a running total from the point this
333: command is given.
334: .It Cm time
335: Display statistics averaged over the refresh interval (the default).
336: .It Cm zero
337: Reset running statistics to zero.
338: .El
339: .It Ic netstat
340: Display, in the lower window, network connections. By default,
341: network servers awaiting requests are not displayed. Each address
342: is displayed in the format ``host.port'', with each shown symbolically,
343: when possible. It is possible to have addresses displayed numerically,
344: limit the display to a set of ports, hosts, and/or protocols
345: (the minimum unambiguous prefix may be supplied):
346: .Pp
347: .Bl -tag -width Ar -compact
348: .It Cm all
349: Toggle the displaying of server processes awaiting requests (this
350: is the equivalent of the
351: .Fl a
352: flag to
353: .Ar netstat 1 ) .
354: .It Cm numbers
355: Display network addresses numerically.
356: .It Cm names
357: Display network addresses symbolically.
358: .It Ar protocol
359: Display only network connections using the indicated protocol
360: (currently either ``tcp'' or ``udp'').
361: .It Cm ignore Op Ar items
362: Do not display information about connections associated with
363: the specified hosts or ports. Hosts and ports may be specified
364: by name (``vangogh'', ``ftp''), or numerically. Host addresses
365: use the Internet dot notation (``128.32.0.9''). Multiple items
366: may be specified with a single command by separating them with
367: spaces.
368: .It Cm display Op Ar items
369: Display information about the connections associated with the
370: specified hosts or ports. As for
371: .Ar ignore ,
372: .Op Ar items
373: may be names or numbers.
374: .It Cm show Op Ar ports\&|hosts
375: Show, on the command line, the currently selected protocols,
376: hosts, and ports. Hosts and ports which are being ignored
377: are prefixed with a `!'. If
378: .Ar ports
379: or
380: .Ar hosts
381: is supplied as an argument to
382: .Cm show ,
383: then only the requested information will be displayed.
384: .It Cm reset
385: Reset the port, host, and protocol matching mechanisms to the default
386: (any protocol, port, or host).
387: .El
388: .El
389: .Pp
390: Commands to switch between displays may be abbreviated to the
391: minimum unambiguous prefix; for example, ``io'' for ``iostat''.
392: Certain information may be discarded when the screen size is
393: insufficient for display. For example, on a machine with 10
394: drives the
395: .Ic iostat
396: bar graph displays only 3 drives on a 24 line terminal. When
397: a bar graph would overflow the allotted screen space it is
398: truncated and the actual value is printed ``over top'' of the bar.
399: .Pp
400: The following commands are common to each display which shows
401: information about disk drives. These commands are used to
402: select a set of drives to report on, should your system have
403: more drives configured than can normally be displayed on the
404: screen.
405: .Pp
406: .Bl -tag -width Tx -compact
407: .It Cm ignore Op Ar drives
408: Do not display information about the drives indicated. Multiple
409: drives may be specified, separated by spaces.
410: .It Cm display Op Ar drives
411: Display information about the drives indicated. Multiple drives
412: may be specified, separated by spaces.
413: .El
414: .Sh FILES
415: .Bl -tag -width /etc/networks -compact
416: .It Pa /netbsd
417: For the namelist.
418: .It Pa /dev/kmem
419: For information in main memory.
420: .It Pa /dev/drum
421: For information about swapped out processes.
422: .It Pa /etc/hosts
423: For host names.
424: .It Pa /etc/networks
425: For network names.
426: .It Pa /etc/services
427: For port names.
428: .El
429: .Sh HISTORY
430: The
431: .Nm systat
432: program appeared in
433: .Bx 4.3 .
434: .Sh BUGS
435: Takes 2-10 percent of the cpu.
436: Certain displays presume a minimum of 80 characters per line.
437: The
438: .Ic vmstat
439: display looks out of place because it is (it was added in as
440: 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