Annotation of src/usr.bin/systat/systat.1, Revision 1.2
1.2 ! deraadt 1: .\" $NetBSD: systat.1,v 1.6 1996/05/10 23:16:39 thorpej Exp $
1.1 deraadt 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
1.2 ! deraadt 44: .Op Fl M Ar core
! 45: .Op Fl N Ar system
! 46: .Op Fl w Ar wait
! 47: .Op Ar display
1.1 deraadt 48: .Op Ar refresh-interval
49: .Sh DESCRIPTION
50: .Nm Systat
51: displays various system statistics in a screen oriented fashion
52: using the curses screen display library,
53: .Xr curses 3 .
54: .Pp
55: While
56: .Nm systat
57: is running the screen is usually divided into two windows (an exception
58: is the vmstat display which uses the entire screen). The
59: upper window depicts the current system load average. The
60: information displayed in the lower window may vary, depending on
61: user commands. The last line on the screen is reserved for user
62: input and error messages.
63: .Pp
64: By default
65: .Nm systat
66: displays the processes getting the largest percentage of the processor
67: in the lower window. Other displays show swap space usage, disk
68: .Tn I/O
69: statistics (a la
70: .Xr iostat 8 ) ,
71: virtual memory statistics (a la
72: .Xr vmstat 8 ) ,
73: network ``mbuf'' utilization, and network connections (a la
74: .Xr netstat 1 ) .
75: .Pp
76: Input is interpreted at two different levels.
77: A ``global'' command interpreter processes all keyboard input.
78: If this command interpreter fails to recognize a command, the
79: input line is passed to a per-display command interpreter. This
80: allows each display to have certain display-specific commands.
81: .Pp
82: Command line options:
83: .Bl -tag -width "refresh_interval"
1.2 ! deraadt 84: .It Fl M Ar core
! 85: Extract values associated with the name list from
! 86: .Ar core
! 87: instead of the default
! 88: .Pa /dev/mem .
! 89: .It Fl N Ar system
! 90: Extracr the name list from
! 91: .Ar system
! 92: instead of the default
! 93: .Pa /netbsd .
! 94: .It Ar display
1.1 deraadt 95: The
96: .Ar display
1.2 ! deraadt 97: argument expects to be one of:
1.1 deraadt 98: .Ic pigs ,
99: .Ic iostat ,
100: .Ic swap ,
101: .Ic mbufs ,
102: .Ic vmstat
103: or
104: .Ic netstat .
1.2 ! deraadt 105: These displays can also be requested interactively and are described in
1.1 deraadt 106: full detail below.
107: .It Ar refresh-interval
108: The
1.2 ! deraadt 109: .Ar refresh-interval
! 110: specifies the screen refresh time interval in seconds. This is provided
! 111: for backwards compatibility, and overrides the
! 112: .Ar refresh-interval
! 113: specified with the
! 114: .Fl w
! 115: flag.
1.1 deraadt 116: .El
117: .Pp
118: Certain characters cause immediate action by
119: .Nm systat .
120: These are
121: .Bl -tag -width Fl
122: .It Ic \&^L
123: Refresh the screen.
124: .It Ic \&^G
125: Print the name of the current ``display'' being shown in
126: the lower window and the refresh interval.
127: .It Ic \&^Z
128: Stop
129: .Nm systat .
130: .It Ic \&:
131: Move the cursor to the command line and interpret the input
132: line typed as a command. While entering a command the
133: current character erase, word erase, and line kill characters
134: may be used.
135: .El
136: .Pp
137: The following commands are interpreted by the ``global''
138: command interpreter.
139: .Bl -tag -width Fl
140: .It Ic help
141: Print the names of the available displays on the command line.
142: .It Ic load
143: Print the load average over the past 1, 5, and 15 minutes
144: on the command line.
145: .It Ic stop
146: Stop refreshing the screen.
147: .It Xo
148: .Op Ic start
149: .Op Ar number
150: .Xc
151: Start (continue) refreshing the screen. If a second, numeric,
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
158: .Nm systat .
159: (This may be abbreviated to
160: .Ic q . )
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
171: is accounted to the ``idle'' process.
172: .It Ic iostat
173: Display, in the lower window, statistics about processor use
174: and disk throughput. Statistics on processor use appear as
175: bar graphs of the amount of time executing in user mode (``user''),
176: in user mode running low priority processes (``nice''), in
177: system mode (``system''), and idle (``idle''). Statistics
178: on disk throughput show, for each drive, kilobytes of data transferred,
1.2 ! deraadt 179: number of disk transactions performed, and time spent in disk accesses
1.1 deraadt 180: (in milliseconds). This information may be displayed as
181: bar graphs or as rows of numbers which scroll downward. Bar
182: graphs are shown by default;
183: .Pp
184: The following commands are specific to the
185: .Ic iostat
186: display; the minimum unambiguous prefix may be supplied.
187: .Pp
188: .Bl -tag -width Fl -compact
189: .It Cm numbers
190: Show the disk
191: .Tn I/O
192: statistics in numeric form. Values are
193: displayed in numeric columns which scroll downward.
194: .It Cm bars
195: Show the disk
196: .Tn I/O
197: statistics in bar graph form (default).
1.2 ! deraadt 198: .It Cm secs
! 199: Toggle the display of time in disk activity (the default is to
! 200: not display time).
1.1 deraadt 201: .El
202: .It Ic swap
203: Show information about swap space usage on all the
204: swap areas compiled into the kernel.
205: The first column is the device name of the partition.
206: The next column is the total space available in the partition.
207: The
208: .Ar Used
209: column indicates the total blocks used so far;
210: the graph shows the percentage of space in use on each partition.
211: If there are more than one swap partition in use,
212: a total line is also shown.
213: Areas known to the kernel, but not in use are shown as not available.
214: .It Ic mbufs
215: Display, in the lower window, the number of mbufs allocated
216: for particular uses, i.e. data, socket structures, etc.
217: .It Ic vmstat
218: Take over the entire display and show a (rather crowded) compendium
219: of statistics related to virtual memory usage, process scheduling,
220: device interrupts, system name translation cacheing, disk
221: .Tn I/O
222: etc.
223: .Pp
224: The upper left quadrant of the screen shows the number
225: of users logged in and the load average over the last one, five,
226: and fifteen minute intervals.
227: Below this line are statistics on memory utilization.
228: The first row of the table reports memory usage only among
229: active processes, that is processes that have run in the previous
230: twenty seconds.
231: The second row reports on memory usage of all processes.
232: The first column reports on the number of physical pages
233: claimed by processes.
234: The second column reports the number of physical pages that
235: are devoted to read only text pages.
236: The third and fourth columns report the same two figures for
237: virtual pages, that is the number of pages that would be
238: needed if all processes had all of their pages.
239: Finally the last column shows the number of physical pages
240: on the free list.
241: .Pp
242: Below the memory display is the disk usage display.
1.2 ! deraadt 243: It reports the number of seeks, transfers, number
1.1 deraadt 244: of kilobyte blocks transferred per second averaged over the
1.2 ! deraadt 245: refresh period of the display (by default, five seconds), and
! 246: the time spent in disk accesses.
1.1 deraadt 247: Note that the system only keeps statistics on at most four disks.
248: .Pp
249: Below the disk display is a list of the
250: average number of processes (over the last refresh interval)
251: that are runnable (`r'), in page wait (`p'),
252: in disk wait other than paging (`d'),
253: sleeping (`s'), and swapped out but desiring to run (`w').
254: Below the queue length listing is a numerical listing and
255: a bar graph showing the amount of
256: system (shown as `='), user (shown as `>'),
257: nice (shown as `-'), and idle time (shown as ` ').
258: .Pp
259: At the bottom left are statistics on name translations.
260: It lists the number of names translated in the previous interval,
261: the number and percentage of the translations that were
262: handled by the system wide name translation cache, and
263: the number and percentage of the translations that were
264: handled by the per process name translation cache.
265: .Pp
266: Under the date in the upper right hand quadrant are statistics
267: on paging and swapping activity.
268: The first two columns report the average number of pages
269: brought in and out per second over the last refresh interval
270: due to page faults and the paging daemon.
271: The third and fourth columns report the average number of pages
272: brought in and out per second over the last refresh interval
273: due to swap requests initiated by the scheduler.
274: The first row of the display shows the average
275: number of disk transfers per second over the last refresh interval;
276: the second row of the display shows the average
277: number of pages transferred per second over the last refresh interval.
278: .Pp
279: Below the paging statistics is a line listing the average number of
280: total reclaims ('Rec'),
281: intransit blocking page faults (`It'),
282: swap text pages found in free list (`F/S'),
283: file system text pages found in free list (`F/F'),
284: reclaims from free list
285: pages freed by the clock daemon (`Fre'),
286: and sequential process pages freed (`SFr')
287: per second over the refresh interval.
288: .Pp
289: Below this line are statistics on the average number of
290: zero filled pages (`zf') and demand filled text pages (`xf')
291: per second over the refresh period.
292: The first row indicates the number of requests that were
293: resolved, the second row shows the number that were set up,
294: and the last row shows the percentage of setup requests that were
295: actually used.
296: Note that this percentage is usually less than 100%,
297: however it may exceed 100% if a large number of requests
298: are actually used long after they were set up during a
299: period when no new pages are being set up.
300: Thus this figure is most interesting when observed over
301: a long time period, such as from boot time
302: (see below on getting such a display).
303: .Pp
304: Below the page fill statistics is a column that
305: lists the average number of context switches (`Csw'),
306: traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'),
307: characters output to DZ ports using
308: .No pseudo Ns -DMA
309: (`Pdm'),
310: network software interrupts (`Sof'),
311: page faults (`Flt'), pages scanned by the page daemon (`Scn'),
312: and revolutions of the page daemon's hand (`Rev')
313: per second over the 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.
322: .Pp
323: The following commands are specific to the
324: .Ic vmstat
325: display; the minimum unambiguous prefix may be supplied.
326: .Pp
327: .Bl -tag -width Ar -compact
328: .It Cm boot
329: Display cumulative statistics since the system was booted.
330: .It Cm run
331: Display statistics as a running total from the point this
332: command is given.
333: .It Cm time
334: Display statistics averaged over the refresh interval (the default).
335: .It Cm zero
336: Reset running statistics to zero.
337: .El
338: .It Ic netstat
339: Display, in the lower window, network connections. By default,
340: network servers awaiting requests are not displayed. Each address
341: is displayed in the format ``host.port'', with each shown symbolically,
342: when possible. It is possible to have addresses displayed numerically,
343: limit the display to a set of ports, hosts, and/or protocols
344: (the minimum unambiguous prefix may be supplied):
345: .Pp
346: .Bl -tag -width Ar -compact
347: .It Cm all
348: Toggle the displaying of server processes awaiting requests (this
349: is the equivalent of the
350: .Fl a
351: flag to
352: .Ar netstat 1 ) .
353: .It Cm numbers
354: Display network addresses numerically.
355: .It Cm names
356: Display network addresses symbolically.
357: .It Ar protocol
358: Display only network connections using the indicated protocol
359: (currently either ``tcp'' or ``udp'').
360: .It Cm ignore Op Ar items
361: Do not display information about connections associated with
362: the specified hosts or ports. Hosts and ports may be specified
363: by name (``vangogh'', ``ftp''), or numerically. Host addresses
364: use the Internet dot notation (``128.32.0.9''). Multiple items
365: may be specified with a single command by separating them with
366: spaces.
367: .It Cm display Op Ar items
368: Display information about the connections associated with the
369: specified hosts or ports. As for
370: .Ar ignore ,
371: .Op Ar items
372: may be names or numbers.
373: .It Cm show Op Ar ports\&|hosts
374: Show, on the command line, the currently selected protocols,
375: hosts, and ports. Hosts and ports which are being ignored
376: are prefixed with a `!'. If
377: .Ar ports
378: or
379: .Ar hosts
380: is supplied as an argument to
381: .Cm show ,
382: then only the requested information will be displayed.
383: .It Cm reset
384: Reset the port, host, and protocol matching mechanisms to the default
385: (any protocol, port, or host).
386: .El
387: .El
388: .Pp
389: Commands to switch between displays may be abbreviated to the
390: minimum unambiguous prefix; for example, ``io'' for ``iostat''.
391: Certain information may be discarded when the screen size is
392: insufficient for display. For example, on a machine with 10
393: drives the
394: .Ic iostat
395: bar graph displays only 3 drives on a 24 line terminal. When
396: a bar graph would overflow the allotted screen space it is
397: truncated and the actual value is printed ``over top'' of the bar.
398: .Pp
399: The following commands are common to each display which shows
400: information about disk drives. These commands are used to
401: select a set of drives to report on, should your system have
402: more drives configured than can normally be displayed on the
403: screen.
404: .Pp
405: .Bl -tag -width Tx -compact
406: .It Cm ignore Op Ar drives
407: Do not display information about the drives indicated. Multiple
408: drives may be specified, separated by spaces.
409: .It Cm display Op Ar drives
410: Display information about the drives indicated. Multiple drives
411: may be specified, separated by spaces.
412: .El
413: .Sh FILES
414: .Bl -tag -width /etc/networks -compact
415: .It Pa /netbsd
416: For the namelist.
417: .It Pa /dev/kmem
418: For information in main memory.
419: .It Pa /dev/drum
420: For information about swapped out processes.
421: .It Pa /etc/hosts
422: For host names.
423: .It Pa /etc/networks
424: For network names.
425: .It Pa /etc/services
426: For port names.
427: .El
428: .Sh HISTORY
429: The
430: .Nm systat
431: program appeared in
432: .Bx 4.3 .
433: .Sh BUGS
434: Takes 2-10 percent of the cpu.
435: Certain displays presume a minimum of 80 characters per line.
436: The
437: .Ic vmstat
438: display looks out of place because it is (it was added in as
439: 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