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