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