1 .\" Copyright (c) 1985, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 4. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)systat.1 8.2 (Berkeley) 12/30/93
36 .Nd display system statistics
40 .Op Ar refresh-interval
44 utility displays various system statistics in a screen oriented fashion
45 using the curses screen display library,
50 is running the screen is usually divided into two windows (an exception
51 is the vmstat display which uses the entire screen).
53 upper window depicts the current system load average.
55 information displayed in the lower window may vary, depending on
57 The last line on the screen is reserved for user
58 input and error messages.
62 displays the processes getting the largest percentage of the processor
64 Other displays show swap space usage, disk
68 virtual memory statistics (a la
72 and network connections (a la
75 Input is interpreted at two different levels.
76 A ``global'' command interpreter processes all keyboard input.
77 If this command interpreter fails to recognize a command, the
78 input line is passed to a per-display command interpreter.
80 allows each display to have certain display-specific commands.
83 .Bl -tag -width "refresh_interval"
102 These displays can also be requested interactively (without the
106 .It Ar refresh-interval
109 specifies the screen refresh time interval in seconds.
110 Time interval can be fractional.
113 Certain characters cause immediate action by
120 Print the name of the current ``display'' being shown in
121 the lower window and the refresh interval.
123 Move the cursor to the command line and interpret the input
124 line typed as a command.
125 While entering a command the
126 current character erase, word erase, and line kill characters
130 The following commands are interpreted by the ``global''
134 Print the names of the available displays on the command line.
136 Print the load average over the past 1, 5, and 15 minutes
139 Stop refreshing the screen.
144 Start (continue) refreshing the screen.
145 If a second, numeric,
146 argument is provided it is interpreted as a refresh interval
148 Supplying only a number will set the refresh interval to this
153 (This may be abbreviated to
157 The available displays are:
160 Display, in the lower window, those processes resident in main
161 memory and getting the
162 largest portion of the processor (the default display).
163 When less than 100% of the
164 processor is scheduled to user processes, the remaining time
165 is accounted to the ``idle'' process.
167 Display, in the lower window, statistics about messages received and
168 transmitted by the Internet Control Message Protocol
170 The left half of the screen displays information about received
171 packets, and the right half displays information regarding transmitted
176 display understands two commands:
182 command is used to select one of four display modes, given as its argument:
183 .Bl -tag -width absoluteXX -compact
185 show the rate of change of each value in packets (the default)
188 show the rate of change of each value in packets per refresh interval
190 show the total change of each value since the display was last reset
192 show the absolute value of each statistic
197 command resets the baseline for
202 command with no argument will display the current mode in the command
205 This display is like the
208 but displays statistics for IPv6 ICMP.
210 Otherwise identical to the
212 display, except that it displays
221 except that it displays
233 Display, in the lower window, statistics about processor use
235 Statistics on processor use appear as
236 bar graphs of the amount of time executing in user mode (``user''),
237 in user mode running low priority processes (``nice''), in
238 system mode (``system''), in interrupt mode (``interrupt''),
241 on disk throughput show, for each drive, megabytes per second,
242 average number of disk transactions per second, and
243 average kilobytes of data per transaction.
244 This information may be
245 displayed as bar graphs or as rows of numbers which scroll downward.
247 graphs are shown by default.
249 The following commands are specific to the
251 display; the minimum unambiguous prefix may be supplied.
253 .Bl -tag -width Fl -compact
257 statistics in numeric form.
259 displayed in numeric columns which scroll downward.
263 statistics in bar graph form (default).
265 Toggle the display of kilobytes per transaction.
267 not display kilobytes per transaction).
270 Show information about swap space usage on all the
271 swap areas compiled into the kernel.
272 The first column is the device name of the partition.
273 The next column is the total space available in the partition.
276 column indicates the total blocks used so far;
277 the graph shows the percentage of space in use on each partition.
278 If there are more than one swap partition in use,
279 a total line is also shown.
280 Areas known to the kernel, but not in use are shown as not available.
282 Take over the entire display and show a (rather crowded) compendium
283 of statistics related to virtual memory usage, process scheduling,
284 device interrupts, system name translation caching, disk
288 The upper left quadrant of the screen shows the number
289 of users logged in and the load average over the last one, five,
290 and fifteen minute intervals.
291 Below this line are statistics on memory utilization.
292 The first row of the table reports memory usage only among
293 active processes, that is processes that have run in the previous
295 The second row reports on memory usage of all processes.
296 The first column reports on the number of kilobytes in physical pages
297 claimed by processes.
298 The second column reports the number of kilobytes in physical pages that
299 are devoted to read only text pages.
300 The third and fourth columns report the same two figures for
301 virtual pages, that is the number of kilobytes in pages that would be
302 needed if all processes had all of their pages.
303 Finally the last column shows the number of kilobytes in physical pages
306 Below the memory display is a list of the
307 average number of processes (over the last refresh interval)
308 that are runnable (`r'), in page wait (`p'),
309 in disk wait other than paging (`d'),
310 sleeping (`s'), and swapped out but desiring to run (`w').
311 The row also shows the average number of context switches
312 (`Csw'), traps (`Trp'; includes page faults), system calls (`Sys'),
313 interrupts (`Int'), network software interrupts (`Sof'), and page
316 Below the process queue length listing is a numerical listing and
317 a bar graph showing the amount of
318 system (shown as `='), interrupt (shown as `+'), user (shown as `>'),
319 nice (shown as `-'), and idle time (shown as ` ').
321 Below the process display are statistics on name translations.
322 It lists the number of names translated in the previous interval,
323 the number and percentage of the translations that were
324 handled by the system wide name translation cache, and
325 the number and percentage of the translations that were
326 handled by the per process name translation cache.
328 To the right of the name translations display are lines showing
329 the number of dirty buffers in the buffer cache (`dtbuf'),
330 desired maximum size of vnode cache (`desvn'),
331 number of vnodes actually allocated (`numvn'),
333 number of allocated vnodes that are free (`frevn').
335 At the bottom left is the disk usage display.
336 It reports the number of
337 kilobytes per transaction, transactions per second, megabytes
338 per second and the percentage of the time the disk was busy averaged
339 over the refresh period of the display (by default, five seconds).
340 The system keeps statistics on most every storage device.
342 to seven devices are displayed.
343 The devices displayed by default are the
344 first devices in the kernel's device list.
349 for details on the devstat system.
351 Under the date in the upper right hand quadrant are statistics
352 on paging and swapping activity.
353 The first two columns report the average number of pages
354 brought in and out per second over the last refresh interval
355 due to page faults and the paging daemon.
356 The third and fourth columns report the average number of pages
357 brought in and out per second over the last refresh interval
358 due to swap requests initiated by the scheduler.
359 The first row of the display shows the average
360 number of disk transfers per second over the last refresh interval;
361 the second row of the display shows the average
362 number of pages transferred per second over the last refresh interval.
364 Below the paging statistics is a column of lines regarding the virtual
366 The first few lines describe,
367 in units (except as noted below)
368 of pages per second averaged over the sampling interval,
369 pages copied on write (`cow'),
370 pages zero filled on demand (`zfod'),
371 pages optimally zero filled on demand (`ozfod'),
372 the ratio of the (average) ozfod / zfod as a percentage (`%ozfod'),
373 pages freed by the page daemon (`daefr'),
374 pages freed by exiting processes (`prcfr'),
375 total pages freed (`totfr'),
376 pages reactivated from the free list (`react'),
377 the average number of
378 times per second that the page daemon was awakened (`pdwak'),
379 pages analyzed by the page daemon (`pdpgs'),
381 in-transit blocking page faults (`intrn').
382 Note that the units are special for `%ozfod' and `pdwak'.
383 The next few lines describe,
384 as amounts of memory in kilobytes,
385 pages wired down (`wire'),
386 active pages (`act'),
387 inactive pages (`inact'),
388 pages on the cache queue (`cache'),
391 Note that the values displayed are the current transient ones;
392 they are not averages.
394 At the bottom of this column is a line showing the
395 amount of virtual memory, in kilobytes, mapped into the buffer cache (`buf').
396 This statistic is not useful.
397 It exists only as a placeholder for the corresponding useful statistic
398 (the amount of real memory used to cache disks).
399 The most important component of the latter (the amount of real memory
400 used by the vm system to cache disks) is not available,
401 but can be guessed from the `inact' amount under some system loads.
403 Running down the right hand side of the display is a breakdown
404 of the interrupts being handled by the system.
405 At the top of the list is the total interrupts per second
406 over the time interval.
407 The rest of the column breaks down the total on a device
409 Only devices that have interrupted at least once since boot time are shown.
411 The following commands are specific to the
413 display; the minimum unambiguous prefix may be supplied.
415 .Bl -tag -width Ar -compact
417 Display cumulative statistics since the system was booted.
419 Display statistics as a running total from the point this
422 Display statistics averaged over the refresh interval (the default).
424 Reset running statistics to zero.
427 Display, in the lower window, network connections.
429 network servers awaiting requests are not displayed.
431 is displayed in the format ``host.port'', with each shown symbolically,
433 It is possible to have addresses displayed numerically,
434 limit the display to a set of ports, hosts, and/or protocols
435 (the minimum unambiguous prefix may be supplied):
437 .Bl -tag -width Ar -compact
439 Toggle the displaying of server processes awaiting requests (this
440 is the equivalent of the
445 Display network addresses numerically.
447 Display network addresses symbolically.
448 .It Cm proto Ar protocol
449 Display only network connections using the indicated
451 Supported protocols are ``tcp'', ``udp'', and ``all''.
452 .It Cm ignore Op Ar items
453 Do not display information about connections associated with
454 the specified hosts or ports.
455 Hosts and ports may be specified
456 by name (``vangogh'', ``ftp''), or numerically.
458 use the Internet dot notation (``128.32.0.9'').
460 may be specified with a single command by separating them with
462 .It Cm display Op Ar items
463 Display information about the connections associated with the
464 specified hosts or ports.
468 may be names or numbers.
469 .It Cm show Op Ar ports\&|hosts
470 Show, on the command line, the currently selected protocols,
472 Hosts and ports which are being ignored
473 are prefixed with a `!'.
478 is supplied as an argument to
480 then only the requested information will be displayed.
482 Reset the port, host, and protocol matching mechanisms to the default
483 (any protocol, port, or host).
486 Display the network traffic going through active interfaces on the
488 Idle interfaces will not be displayed until they receive some
491 For each interface being displayed, the current, peak and total
492 statistics are displayed for incoming and outgoing traffic.
496 display will automatically scale the units being used so that they are
497 in a human-readable format.
498 The scaling units used for the current and
500 traffic columns can be altered by the
503 .Bl -tag -width ".Cm scale Op Ar units"
504 .It Cm scale Op Ar units
505 Modify the scale used to display the current and peak traffic over all
507 The following units are recognised: kbit, kbyte, mbit,
508 mbyte, gbit, gbyte and auto.
510 Show statistics in packets per second instead of bytes/bits per second.
513 switches this mode off.
514 .It Cm match Op Ar patterns
515 Display only interfaces that match pattern provided as an argument.
516 Patterns should be in shell syntax separated by whitespaces or commas.
517 If this command is called without arguments then all interfaces are displayed.
522 This will display em0 and bge1 interfaces.
524 .Dl match em*, bge*, lo0
526 This will display all
530 interfaces and the loopback interface.
534 Commands to switch between displays may be abbreviated to the
535 minimum unambiguous prefix; for example, ``io'' for ``iostat''.
536 Certain information may be discarded when the screen size is
537 insufficient for display.
538 For example, on a machine with 10
541 bar graph displays only 3 drives on a 24 line terminal.
543 a bar graph would overflow the allotted screen space it is
544 truncated and the actual value is printed ``over top'' of the bar.
546 The following commands are common to each display which shows
547 information about disk drives.
548 These commands are used to
549 select a set of drives to report on, should your system have
550 more drives configured than can normally be displayed on the
553 .Bl -tag -width Ar -compact
554 .It Cm ignore Op Ar drives
555 Do not display information about the drives indicated.
557 drives may be specified, separated by spaces.
558 .It Cm display Op Ar drives
559 Display information about the drives indicated.
561 may be specified, separated by spaces.
562 .It Cm only Op Ar drives
563 Display only the specified drives.
564 Multiple drives may be specified,
567 Display a list of available devices.
569 .Ar type , Ns Ar if , Ns Ar pass
572 Display devices matching the given pattern.
574 expressions are the same as those used in
577 Instead of specifying multiple
579 arguments which are then ORed together, the user instead specifies multiple
580 matching expressions joined by the pipe
584 separated arguments within each matching expression are ANDed together, and
585 then the pipe separated matching expressions are ORed together.
587 device matching the combined expression will be displayed, if there is room
591 .Dl match da,scsi | cd,ide
593 This will display all SCSI Direct Access devices and all IDE CDROM devices.
595 .Dl match da | sa | cd,pass
597 This will display all Direct Access devices, all Sequential Access devices,
598 and all passthrough devices that provide access to CDROM drives.
601 .Bl -tag -width /boot/kernel/kernel -compact
602 .It Pa /boot/kernel/kernel
605 For information in main memory.
637 the notion of having different display modes for the
643 statistics was stolen from the
651 Certain displays presume a minimum of 80 characters per line.
654 display looks out of place because it is (it was added in as
655 a separate display rather than created as a new program).