1.\" $NetBSD: systat.1,v 1.33 2003/09/15 13:17:24 wiz 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)systat.1 8.2 (Berkeley) 12/30/93 31.\" 32.Dd September 12, 2003 33.Dt SYSTAT 1 34.Os 35.Sh NAME 36.Nm systat 37.Nd display system statistics on a CRT 38.Sh SYNOPSIS 39.Nm 40.Op Fl n 41.Op Fl M Ar core 42.Op Fl N Ar system 43.Op Fl t Ar turns 44.Op Fl w Ar wait 45.Op Ar display 46.Op Ar refresh-interval 47.Sh DESCRIPTION 48.Nm 49displays various system statistics in a screen oriented fashion 50using the curses screen display library, 51.Xr curses 3 . 52.Pp 53While 54.Nm 55is running the screen is usually divided into two windows (an exception 56is the vmstat display which uses the entire screen). 57The upper window depicts the current system load average. 58The information displayed in the lower window may vary, depending on 59user commands. 60The last line on the screen is reserved for user input and error messages. 61.Pp 62By default 63.Nm 64displays the processes getting the largest percentage of the processor 65in the lower window. 66Other displays show more detailed process information, swap space usage, disk 67.Tn I/O 68statistics (a la 69.Xr iostat 8 ) , 70virtual memory statistics (a la 71.Xr vmstat 1 ) , 72network ``mbuf'' utilization, and network connections (a la 73.Xr netstat 1 ) . 74.Pp 75Input is interpreted at two different levels. 76A ``global'' command interpreter processes all keyboard input. 77If this command interpreter fails to recognize a command, the 78input line is passed to a per-display command interpreter. 79This allows each display to have certain display-specific commands. 80.Pp 81Command line options: 82.Bl -tag -width "refresh_interval" 83.It Fl M Ar core 84Extract values associated with the name list from 85.Ar core 86instead of the default 87.Pa /dev/mem . 88.It Fl N Ar system 89Extract the name list from 90.Ar system 91instead of the default 92.Pa /netbsd . 93.It Fl n 94Do not resolve IP addresses into string hostnames 95.Pq FQDNs 96on 97.Ic netstat . 98It has the same effect as 99.Ic numbers 100subcommand in 101.Ic netstat . 102.It Fl w Ar wait 103See 104.Ar refresh-interval . 105.It Fl t Ar turns 106How many refreshes to show each screen in 'all' display mode. 107.It Ar display 108The 109.Ar display 110argument expects to be one of: 111.Ic all , 112.Ic bufcache , 113.Ic inet.icmp , 114.Ic inet.ip , 115.Ic inet.tcp , 116.Ic inet.tcpsyn , 117.Ic inet6.ip6 , 118.Ic ipsec , 119.Ic iostat , 120.Ic mbufs , 121.Ic netstat , 122.Ic pigs , 123.Ic ps , 124.Ic swap 125or 126.Ic vmstat . 127These displays can also be requested interactively and are described in 128full detail below. 129.It Ar refresh-interval 130The 131.Ar refresh-interval 132specifies the screen refresh time interval in seconds. 133This is provided for backwards compatibility, and overrides the 134.Ar refresh-interval 135specified with the 136.Fl w 137flag. 138.El 139.Pp 140Certain characters cause immediate action by 141.Nm . 142These are 143.Bl -tag -width Fl 144.It Ic \&^L 145Refresh the screen. 146.It Ic \&^G 147Print the name of the current ``display'' being shown in 148the lower window and the refresh interval. 149.It Ic \&^Z 150Stop 151.Nm . 152.It Ic \&? , Ic h 153Print the names of the available displays on the command line. 154.It Ic \&: 155Move the cursor to the command line and interpret the input 156line typed as a command. 157While entering a command the current character erase, word erase, 158and line kill characters may be used. 159.El 160.Pp 161The following commands are interpreted by the ``global'' 162command interpreter. 163.Bl -tag -width Fl 164.It Ic help Ar key 165Print the names of the available displays on the command line. 166It will print long names as 167.Dq Ic inet.* . 168To print items under 169.Dq Ic inet , 170give 171.Ic inet 172as 173.Ar key . 174.It Ic load 175Print the load average over the past 1, 5, and 15 minutes 176on the command line. 177.It Ic stop 178Stop refreshing the screen. 179.It Xo 180.Op Ic start 181.Op Ar number 182.Xc 183Start (continue) refreshing the screen. 184If a second, numeric, argument is provided it is interpreted as a 185refresh interval in seconds. 186Supplying only a number will set the refresh interval to this 187value. 188.It Ic quit 189Exit 190.Nm . 191(This may be abbreviated to 192.Ic q . ) 193.El 194.Pp 195The available displays are: 196.Bl -tag -width Ic 197.It Ic all 198Cycle through all displays automatically. 199At each display, wait some 200refresh-turns, then switch to the next display. 201Duration of one refresh-turn is adjustable with the 202.Fl w 203option, number of refresh-turns can be changed with the 204.Fl t 205option. 206.It Ic bufcache 207Display, in the lower window, statistics about the file system buffers. 208Statistics for each file system that has active buffers include the number 209of buffers for that file system, the number of active kilobytes in those 210buffers and the total size of the buffers for that file system. 211.It Ic inet.icmp 212Display ICMP statistics. 213.It Ic inet.ip 214Display IPv4 and UDP statistics. 215.It Ic inet.tcp 216Display TCP statistics. 217.It Ic inet.tcpsyn 218Display statistics about the 219.Tn TCP 220``syncache''. 221.It Ic inet6.ip6 222Display IPv6 statistics. 223.It Ic ipsec 224Display IPsec statistics for both IPv4 and v6. 225.It Ic iostat 226Display, in the lower window, statistics about processor use 227and disk throughput. 228Statistics on processor use appear as bar graphs of the amount of 229time executing in user mode (``user''), in user mode running low 230priority processes (``nice''), in system mode (``system''), and 231idle (``idle''). 232Statistics on disk throughput show, for each drive, kilobytes of 233data transferred, number of disk transactions performed, and time 234spent in disk accesses in milliseconds. 235This information may be displayed as bar graphs or as rows of 236numbers which scroll downward. 237Bar graphs are shown by default; 238.Pp 239The following commands are specific to the 240.Ic iostat 241display; the minimum unambiguous prefix may be supplied. 242.Pp 243.Bl -tag -width Fl -compact 244.It Cm numbers 245Show the disk 246.Tn I/O 247statistics in numeric form. 248Values are 249displayed in numeric columns which scroll downward. 250.It Cm bars 251Show the disk 252.Tn I/O 253statistics in bar graph form (default). 254.It Cm secs 255Toggle the display of time in disk activity (the default is to 256not display time). 257.It Cm all 258Show the read and write statistics combined (default). 259.It Cm rw 260Show the read and write statistics separately. 261.El 262.It Ic mbufs 263Display, in the lower window, the number of mbufs allocated 264for particular uses, i.e. data, socket structures, etc. 265.It Ic netstat 266Display, in the lower window, network connections. 267By default, network servers awaiting requests are not displayed. 268Each address is displayed in the format ``host.port'', with each 269shown symbolically, when possible. 270It is possible to have addresses displayed numerically, 271limit the display to a set of ports, hosts, and/or protocols 272(the minimum unambiguous prefix may be supplied): 273.Pp 274.Bl -tag -width Ar -compact 275.It Cm all 276Toggle the displaying of server processes awaiting requests (this 277is the equivalent of the 278.Fl a 279flag to 280.Ar netstat 1 ) . 281.It Cm numbers 282Display network addresses numerically. 283.It Cm names 284Display network addresses symbolically. 285.It Ar protocol 286Display only network connections using the indicated protocol 287(currently either ``tcp'' or ``udp''). 288.It Cm ignore Op Ar items 289Do not display information about connections associated with 290the specified hosts or ports. 291Hosts and ports may be specified by name (``vangogh'', ``ftp''), 292or numerically. 293Host addresses use the Internet dot notation (``128.32.0.9''). 294Multiple items may be specified with a single command by separating 295them with spaces. 296.It Cm display Op Ar items 297Display information about the connections associated with the 298specified hosts or ports. 299As for 300.Ar ignore , 301.Op Ar items 302may be names or numbers. 303.It Cm show Op Ar ports\&|hosts 304Show, on the command line, the currently selected protocols, 305hosts, and ports. 306Hosts and ports which are being ignored are prefixed with a `!'. 307If 308.Ar ports 309or 310.Ar hosts 311is supplied as an argument to 312.Cm show , 313then only the requested information will be displayed. 314.It Cm reset 315Reset the port, host, and protocol matching mechanisms to the default 316(any protocol, port, or host). 317.El 318.It Ic pigs 319Display, in the lower window, those processes resident in main 320memory and getting the 321largest portion of the processor (the default display). 322When less than 100% of the 323processor is scheduled to user processes, the remaining time 324is accounted to the ``idle'' process. 325.It Ic ps 326Display, in the lower window, the same information provided 327by the command 328.Xr ps 1 329with the flags 330.Fl aux . 331.Pp 332The following command is specific to the 333.Ic ps 334display; the minimum unambiguous prefix may be supplied. 335.Pp 336.Bl -tag -width Fl -compact 337.It Cm user Ar name 338Limit the list of processes displayed to those owned by user 339.Ar name . 340If 341.Ar name 342is specified as `+', processes owned by any user are displayed (default). 343.El 344.It Ic swap 345Show information about swap space usage on all the 346swap areas configured with 347.Xr swapctl 8 . 348The first column is the device name of the partition. 349The next column is the total space available in the partition. 350The 351.Ar Used 352column indicates the total blocks used so far; 353the graph shows the percentage of space in use on each partition. 354If there are more than one swap partition in use, 355a total line is also shown. 356Areas known to the kernel, but not in use are shown as not available. 357.It Ic vmstat 358Take over the entire display and show a (rather crowded) compendium 359of statistics related to virtual memory usage, process scheduling, 360device interrupts, system name translation caching, disk 361.Tn I/O 362etc. 363.Pp 364The upper left quadrant of the screen shows the number 365of users logged in and the load average over the last one, five, 366and fifteen minute intervals. 367Below this is a list of the 368average number of processes (over the last refresh interval) 369that are runnable (`r'), in page wait (`p'), 370in disk wait other than paging (`d'), 371sleeping (`s'), and swapped out but desiring to run (`w'). 372Below the queue length listing is a numerical listing and 373a bar graph showing the amount of 374system (shown as `='), user (shown as `\*[Gt]'), 375nice (shown as `-'), and idle time (shown as ` '). 376.Pp 377To the right of the process statistics is a column that 378lists the average number of context switches (`Csw'), 379traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'), 380network software interrupts (`Sof'), 381page faults (`Flt'). 382.Pp 383Below this are statistics on memory utilization. 384The first row of the table reports memory usage only among 385active processes, that is processes that have run in the previous 386twenty seconds. 387The second row reports on memory usage of all processes. 388The first column reports on the number of physical pages 389claimed by processes. 390The second column reports the number of pages of memory and swap. 391The third column gives the number of pages of free memory and swap. 392.Pp 393Below the memory display are statistics on name translations. 394It lists the number of names translated in the previous interval, 395the number and percentage of the translations that were 396handled by the system wide name translation cache, and 397the number and percentage of the translations that were 398handled by the per process name translation cache. 399.Pp 400At the bottom left is the disk usage display. 401It reports the number of seeks, transfers, number 402of kilobyte blocks transferred per second averaged over the 403refresh period of the display (by default, five seconds), and 404the time spent in disk accesses. 405If there are more than five disks, and the terminal window has more 406than 24 lines, the disks display will be flipped so that more 407of the disk statistics are visible. 408.Pp 409Under the date in the upper right hand quadrant are statistics 410on paging and swapping activity. 411The first two columns report the average number of pages 412brought in and out per second over the last refresh interval 413due to page faults and the paging daemon. 414The third and fourth columns report the average number of pages 415brought in and out per second over the last refresh interval 416due to swap requests initiated by the scheduler. 417The first row of the display shows the average 418number of disk transfers per second over the last refresh interval; 419the second row of the display shows the average 420number of pages transferred per second over the last refresh interval. 421.Pp 422Below the paging statistics is another columns of paging data. 423From top to bottom, these represent average numbers of copy on write faults 424(`cow'), object cache lookups (`objlk'), object cache hits (`objht'), 425pages zero filled on demand (`zfodw'), number zfod's created (`nzfod'), 426percentage of zfod's used (`%zfod'), number of kernel pages (`kern'), 427number of wired pages (`wire'), number of active pages (`act'), number 428of inactive pages (`inact'), number of free pages (`free'), pages freed 429by daemon (`daefr'), pages freed by exiting processes (`prcfr'), number 430of pages reactivated from freelist (`react'), scans in page out daemon 431(`scan'), revolutions of the hand (`hdrev'), and in-transit blocking page 432faults (`intrn'), per second over the refresh period. 433Note that the `%zfod' percentage is usually less than 100%, 434however it may exceed 100% if a large number of requests 435are actually used long after they were set up during a 436period when no new pages are being set up. 437Thus this figure is most interesting when observed over 438a long time period, such as from boot time 439(see below on getting such a display). 440.Pp 441To the left of the column of paging statistics is a breakdown 442of the interrupts being handled by the system. 443At the top of the list is the total interrupts per second 444over the time interval. 445The rest of the column breaks down the total on a device 446by device basis. 447Only devices that have interrupted at least once since boot time are shown. 448.El 449.Pp 450Commands to switch between displays may be abbreviated to the 451minimum unambiguous prefix; for example, ``io'' for ``iostat''. 452Certain information may be discarded when the screen size is 453insufficient for display. 454For example, on a machine with 10 drives the 455.Ic iostat 456bar graph displays only 3 drives on a 24 line terminal. 457When a bar graph would overflow the allotted screen space it is 458truncated and the actual value is printed ``over top'' of the bar. 459.Pp 460The following commands are common to each display which shows 461information about disk drives. 462These commands are used to select a set of drives to report on, 463should your system have more drives configured than can normally 464be displayed on the screen. 465.Pp 466.Bl -tag -width Ar -compact 467.It Cm display Op Ar drives 468Display information about the drives indicated. 469Multiple drives may be specified, separated by spaces. 470.It Cm ignore Op Ar drives 471Do not display information about the drives indicated. 472Multiple drives may be specified, separated by spaces. 473.It Cm drives Op Ar drives 474With no arguments, display a list of available drives. 475With arguments, replace the list of currently displayed drives 476with the ones specified. 477.El 478.Pp 479The following commands are specific to the 480.Ic inet.* , 481.Ic inet6.* , 482.Ic ipsec 483and 484.Ic vmstat 485displays; the minimum unambiguous prefix may be supplied. 486.Pp 487.Bl -tag -width Ar -compact 488.It Cm boot 489Display cumulative statistics since the system was booted. 490.It Cm run 491Display statistics as a running total from the point this 492command is given. 493.It Cm time 494Display statistics averaged over the refresh interval (the default). 495.It Cm zero 496Reset running statistics to zero. 497.El 498.Sh FILES 499.Bl -tag -width /etc/networks -compact 500.It Pa /netbsd 501For the namelist. 502.It Pa /dev/kmem 503For information in main memory. 504.It Pa /dev/drum 505For information about swapped out processes. 506.It Pa /etc/hosts 507For host names. 508.It Pa /etc/networks 509For network names. 510.It Pa /etc/services 511For port names. 512.El 513.Sh NOTES 514Much of the information that 515.Nm 516.Ic vmstat 517uses is obtained from 518.Cm struct vmmeter cnt . 519.Sh SEE ALSO 520.Xr netstat 1 , 521.Xr ps 1 , 522.Xr top 1 , 523.Xr vmstat 1 , 524.Xr iostat 8 , 525.Xr pstat 8 526.Sh HISTORY 527The 528.Nm 529program appeared in 530.Bx 4.3 . 531.Sh BUGS 532Consumes CPU resources and thus may skew statistics. 533.Pp 534Certain displays presume a minimum of 80 characters per line. 535.Pp 536The 537.Ic vmstat 538display looks out of place because it is (it was added in as 539a separate display from what used to be a different program). 540