Annotation of src/usr.bin/systat/systat.1, Revision 1.1.1.1
1.1 deraadt 1: .\" $NetBSD: systat.1,v 1.5 1995/09/27 19:46:12 jtc Exp $
2: .\"
3: .\" Copyright (c) 1985, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
14: .\" 3. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" @(#)systat.1 8.2 (Berkeley) 12/30/93
35: .\"
36: .Dd December 30, 1993
37: .Dt SYSTAT 1
38: .Os BSD 4.3
39: .Sh NAME
40: .Nm systat
41: .Nd display system statistics on a crt
42: .Sh SYNOPSIS
43: .Nm systat
44: .Op Fl display
45: .Op Ar refresh-interval
46: .Sh DESCRIPTION
47: .Nm Systat
48: displays various system statistics in a screen oriented fashion
49: using the curses screen display library,
50: .Xr curses 3 .
51: .Pp
52: While
53: .Nm systat
54: is running the screen is usually divided into two windows (an exception
55: is the vmstat display which uses the entire screen). The
56: upper window depicts the current system load average. The
57: information displayed in the lower window may vary, depending on
58: user commands. The last line on the screen is reserved for user
59: input and error messages.
60: .Pp
61: By default
62: .Nm systat
63: displays the processes getting the largest percentage of the processor
64: in the lower window. Other displays show swap space usage, disk
65: .Tn I/O
66: statistics (a la
67: .Xr iostat 8 ) ,
68: virtual memory statistics (a la
69: .Xr vmstat 8 ) ,
70: network ``mbuf'' utilization, and network connections (a la
71: .Xr netstat 1 ) .
72: .Pp
73: Input is interpreted at two different levels.
74: A ``global'' command interpreter processes all keyboard input.
75: If this command interpreter fails to recognize a command, the
76: input line is passed to a per-display command interpreter. This
77: allows each display to have certain display-specific commands.
78: .Pp
79: Command line options:
80: .Bl -tag -width "refresh_interval"
81: .It Fl Ns Ar display
82: The
83: .Fl
84: flag expects
85: .Ar display
86: to be one of:
87: .Ic pigs ,
88: .Ic iostat ,
89: .Ic swap ,
90: .Ic mbufs ,
91: .Ic vmstat
92: or
93: .Ic netstat .
94: These displays can also be requested interactively (without the
95: .Dq Fl )
96: and are described in
97: full detail below.
98: .It Ar refresh-interval
99: The
100: .Ar refresh-value
101: specifies the screen refresh time interval in seconds.
102: .El
103: .Pp
104: Certain characters cause immediate action by
105: .Nm systat .
106: These are
107: .Bl -tag -width Fl
108: .It Ic \&^L
109: Refresh the screen.
110: .It Ic \&^G
111: Print the name of the current ``display'' being shown in
112: the lower window and the refresh interval.
113: .It Ic \&^Z
114: Stop
115: .Nm systat .
116: .It Ic \&:
117: Move the cursor to the command line and interpret the input
118: line typed as a command. While entering a command the
119: current character erase, word erase, and line kill characters
120: may be used.
121: .El
122: .Pp
123: The following commands are interpreted by the ``global''
124: command interpreter.
125: .Bl -tag -width Fl
126: .It Ic help
127: Print the names of the available displays on the command line.
128: .It Ic load
129: Print the load average over the past 1, 5, and 15 minutes
130: on the command line.
131: .It Ic stop
132: Stop refreshing the screen.
133: .It Xo
134: .Op Ic start
135: .Op Ar number
136: .Xc
137: Start (continue) refreshing the screen. If a second, numeric,
138: argument is provided it is interpreted as a refresh interval
139: (in seconds).
140: Supplying only a number will set the refresh interval to this
141: value.
142: .It Ic quit
143: Exit
144: .Nm systat .
145: (This may be abbreviated to
146: .Ic q . )
147: .El
148: .Pp
149: The available displays are:
150: .Bl -tag -width Ic
151: .It Ic pigs
152: Display, in the lower window, those processes resident in main
153: memory and getting the
154: largest portion of the processor (the default display).
155: When less than 100% of the
156: processor is scheduled to user processes, the remaining time
157: is accounted to the ``idle'' process.
158: .It Ic iostat
159: Display, in the lower window, statistics about processor use
160: and disk throughput. Statistics on processor use appear as
161: bar graphs of the amount of time executing in user mode (``user''),
162: in user mode running low priority processes (``nice''), in
163: system mode (``system''), and idle (``idle''). Statistics
164: on disk throughput show, for each drive, kilobytes of data transferred,
165: number of disk transactions performed, and average seek time
166: (in milliseconds). This information may be displayed as
167: bar graphs or as rows of numbers which scroll downward. Bar
168: graphs are shown by default;
169: .Pp
170: The following commands are specific to the
171: .Ic iostat
172: display; the minimum unambiguous prefix may be supplied.
173: .Pp
174: .Bl -tag -width Fl -compact
175: .It Cm numbers
176: Show the disk
177: .Tn I/O
178: statistics in numeric form. Values are
179: displayed in numeric columns which scroll downward.
180: .It Cm bars
181: Show the disk
182: .Tn I/O
183: statistics in bar graph form (default).
184: .It Cm msps
185: Toggle the display of average seek time (the default is to
186: not display seek times).
187: .El
188: .It Ic swap
189: Show information about swap space usage on all the
190: swap areas compiled into the kernel.
191: The first column is the device name of the partition.
192: The next column is the total space available in the partition.
193: The
194: .Ar Used
195: column indicates the total blocks used so far;
196: the graph shows the percentage of space in use on each partition.
197: If there are more than one swap partition in use,
198: a total line is also shown.
199: Areas known to the kernel, but not in use are shown as not available.
200: .It Ic mbufs
201: Display, in the lower window, the number of mbufs allocated
202: for particular uses, i.e. data, socket structures, etc.
203: .It Ic vmstat
204: Take over the entire display and show a (rather crowded) compendium
205: of statistics related to virtual memory usage, process scheduling,
206: device interrupts, system name translation cacheing, disk
207: .Tn I/O
208: etc.
209: .Pp
210: The upper left quadrant of the screen shows the number
211: of users logged in and the load average over the last one, five,
212: and fifteen minute intervals.
213: Below this line are statistics on memory utilization.
214: The first row of the table reports memory usage only among
215: active processes, that is processes that have run in the previous
216: twenty seconds.
217: The second row reports on memory usage of all processes.
218: The first column reports on the number of physical pages
219: claimed by processes.
220: The second column reports the number of physical pages that
221: are devoted to read only text pages.
222: The third and fourth columns report the same two figures for
223: virtual pages, that is the number of pages that would be
224: needed if all processes had all of their pages.
225: Finally the last column shows the number of physical pages
226: on the free list.
227: .Pp
228: Below the memory display is the disk usage display.
229: It reports the number of seeks, transfers, and number
230: of kilobyte blocks transferred per second averaged over the
231: refresh period of the display (by default, five seconds).
232: For some disks it also reports the average milliseconds per seek.
233: Note that the system only keeps statistics on at most four disks.
234: .Pp
235: Below the disk display is a list of the
236: average number of processes (over the last refresh interval)
237: that are runnable (`r'), in page wait (`p'),
238: in disk wait other than paging (`d'),
239: sleeping (`s'), and swapped out but desiring to run (`w').
240: Below the queue length listing is a numerical listing and
241: a bar graph showing the amount of
242: system (shown as `='), user (shown as `>'),
243: nice (shown as `-'), and idle time (shown as ` ').
244: .Pp
245: At the bottom left are statistics on name translations.
246: It lists the number of names translated in the previous interval,
247: the number and percentage of the translations that were
248: handled by the system wide name translation cache, and
249: the number and percentage of the translations that were
250: handled by the per process name translation cache.
251: .Pp
252: Under the date in the upper right hand quadrant are statistics
253: on paging and swapping activity.
254: The first two columns report the average number of pages
255: brought in and out per second over the last refresh interval
256: due to page faults and the paging daemon.
257: The third and fourth columns report the average number of pages
258: brought in and out per second over the last refresh interval
259: due to swap requests initiated by the scheduler.
260: The first row of the display shows the average
261: number of disk transfers per second over the last refresh interval;
262: the second row of the display shows the average
263: number of pages transferred per second over the last refresh interval.
264: .Pp
265: Below the paging statistics is a line listing the average number of
266: total reclaims ('Rec'),
267: intransit blocking page faults (`It'),
268: swap text pages found in free list (`F/S'),
269: file system text pages found in free list (`F/F'),
270: reclaims from free list
271: pages freed by the clock daemon (`Fre'),
272: and sequential process pages freed (`SFr')
273: per second over the refresh interval.
274: .Pp
275: Below this line are statistics on the average number of
276: zero filled pages (`zf') and demand filled text pages (`xf')
277: per second over the refresh period.
278: The first row indicates the number of requests that were
279: resolved, the second row shows the number that were set up,
280: and the last row shows the percentage of setup requests that were
281: actually used.
282: Note that this percentage is usually less than 100%,
283: however it may exceed 100% if a large number of requests
284: are actually used long after they were set up during a
285: period when no new pages are being set up.
286: Thus this figure is most interesting when observed over
287: a long time period, such as from boot time
288: (see below on getting such a display).
289: .Pp
290: Below the page fill statistics is a column that
291: lists the average number of context switches (`Csw'),
292: traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'),
293: characters output to DZ ports using
294: .No pseudo Ns -DMA
295: (`Pdm'),
296: network software interrupts (`Sof'),
297: page faults (`Flt'), pages scanned by the page daemon (`Scn'),
298: and revolutions of the page daemon's hand (`Rev')
299: per second over the refresh interval.
300: .Pp
301: Running down the right hand side of the display is a breakdown
302: of the interrupts being handled by the system.
303: At the top of the list is the total interrupts per second
304: over the time interval.
305: The rest of the column breaks down the total on a device
306: by device basis.
307: Only devices that have interrupted at least once since boot time are shown.
308: .Pp
309: The following commands are specific to the
310: .Ic vmstat
311: display; the minimum unambiguous prefix may be supplied.
312: .Pp
313: .Bl -tag -width Ar -compact
314: .It Cm boot
315: Display cumulative statistics since the system was booted.
316: .It Cm run
317: Display statistics as a running total from the point this
318: command is given.
319: .It Cm time
320: Display statistics averaged over the refresh interval (the default).
321: .It Cm zero
322: Reset running statistics to zero.
323: .El
324: .It Ic netstat
325: Display, in the lower window, network connections. By default,
326: network servers awaiting requests are not displayed. Each address
327: is displayed in the format ``host.port'', with each shown symbolically,
328: when possible. It is possible to have addresses displayed numerically,
329: limit the display to a set of ports, hosts, and/or protocols
330: (the minimum unambiguous prefix may be supplied):
331: .Pp
332: .Bl -tag -width Ar -compact
333: .It Cm all
334: Toggle the displaying of server processes awaiting requests (this
335: is the equivalent of the
336: .Fl a
337: flag to
338: .Ar netstat 1 ) .
339: .It Cm numbers
340: Display network addresses numerically.
341: .It Cm names
342: Display network addresses symbolically.
343: .It Ar protocol
344: Display only network connections using the indicated protocol
345: (currently either ``tcp'' or ``udp'').
346: .It Cm ignore Op Ar items
347: Do not display information about connections associated with
348: the specified hosts or ports. Hosts and ports may be specified
349: by name (``vangogh'', ``ftp''), or numerically. Host addresses
350: use the Internet dot notation (``128.32.0.9''). Multiple items
351: may be specified with a single command by separating them with
352: spaces.
353: .It Cm display Op Ar items
354: Display information about the connections associated with the
355: specified hosts or ports. As for
356: .Ar ignore ,
357: .Op Ar items
358: may be names or numbers.
359: .It Cm show Op Ar ports\&|hosts
360: Show, on the command line, the currently selected protocols,
361: hosts, and ports. Hosts and ports which are being ignored
362: are prefixed with a `!'. If
363: .Ar ports
364: or
365: .Ar hosts
366: is supplied as an argument to
367: .Cm show ,
368: then only the requested information will be displayed.
369: .It Cm reset
370: Reset the port, host, and protocol matching mechanisms to the default
371: (any protocol, port, or host).
372: .El
373: .El
374: .Pp
375: Commands to switch between displays may be abbreviated to the
376: minimum unambiguous prefix; for example, ``io'' for ``iostat''.
377: Certain information may be discarded when the screen size is
378: insufficient for display. For example, on a machine with 10
379: drives the
380: .Ic iostat
381: bar graph displays only 3 drives on a 24 line terminal. When
382: a bar graph would overflow the allotted screen space it is
383: truncated and the actual value is printed ``over top'' of the bar.
384: .Pp
385: The following commands are common to each display which shows
386: information about disk drives. These commands are used to
387: select a set of drives to report on, should your system have
388: more drives configured than can normally be displayed on the
389: screen.
390: .Pp
391: .Bl -tag -width Tx -compact
392: .It Cm ignore Op Ar drives
393: Do not display information about the drives indicated. Multiple
394: drives may be specified, separated by spaces.
395: .It Cm display Op Ar drives
396: Display information about the drives indicated. Multiple drives
397: may be specified, separated by spaces.
398: .El
399: .Sh FILES
400: .Bl -tag -width /etc/networks -compact
401: .It Pa /netbsd
402: For the namelist.
403: .It Pa /dev/kmem
404: For information in main memory.
405: .It Pa /dev/drum
406: For information about swapped out processes.
407: .It Pa /etc/hosts
408: For host names.
409: .It Pa /etc/networks
410: For network names.
411: .It Pa /etc/services
412: For port names.
413: .El
414: .Sh HISTORY
415: The
416: .Nm systat
417: program appeared in
418: .Bx 4.3 .
419: .Sh BUGS
420: Takes 2-10 percent of the cpu.
421: Certain displays presume a minimum of 80 characters per line.
422: The
423: .Ic vmstat
424: display looks out of place because it is (it was added in as
425: 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