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