1.\" $OpenBSD: systat.1,v 1.92 2011/04/29 05:48:04 lum Exp $ 2.\" $NetBSD: systat.1,v 1.6 1996/05/10 23:16:39 thorpej Exp $ 3.\" 4.\" Copyright (c) 1985, 1990, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)systat.1 8.2 (Berkeley) 12/30/93 32.\" 33.Dd $Mdocdate: April 29 2011 $ 34.Dt SYSTAT 1 35.Os 36.Sh NAME 37.Nm systat 38.Nd display system statistics 39.Sh SYNOPSIS 40.Nm systat 41.Op Fl abiNn 42.Op Fl d Ar count 43.Op Fl s Ar delay 44.Op Fl w Ar width 45.Op Ar view 46.Op Ar delay 47.Sh DESCRIPTION 48.Nm 49displays various system statistics in a screen-oriented fashion 50using the 51.Xr curses 3 52screen display library. 53.Pp 54While 55.Nm 56is running, the screen is divided into different areas. 57The top line displays the current number of users, the 58three system load average figures over the last 1, 5, and 5915 minute intervals, and the system time. 60The bottom line of the screen is reserved for 61user input and error messages. 62The information displayed in the rest of the screen 63comprises a 64.Em view , 65and is the main interface for 66displaying different types of system statistics. 67The 68.Ic vmstat 69view is the default. 70.Pp 71Certain information may be discarded when the screen size is 72insufficient for display. 73For example, on a machine with 10 drives the 74.Ic iostat 75bar graph displays only 3 drives on a 24 line terminal. 76.\".Pp 77.\"Input is interpreted at two different levels. 78.\"A 79.\".Dq global 80.\"command interpreter processes all keyboard input. 81.\"If this command interpreter fails to recognize a command, the 82.\"input line is passed to a per-display command interpreter. 83.\"This allows each display to have certain display-specific commands. 84.Pp 85The options are as follows: 86.Bl -tag -width Ds 87.It Fl a 88Display all lines. 89.It Fl b 90Raw, non-interactive mode. 91.It Fl d Ar count 92Exit after 93.Ar count 94screen updates. 95.It Fl i 96Interactive mode. 97.It Fl N 98Resolve network addresses to names. 99This is the opposite of the 100.Fl n 101option. 102.It Fl n 103Do not try to reverse map IP addresses. 104This is the default. 105.It Fl s Ar delay 106Specifies the screen refresh time interval in seconds. 107This option is overridden by the final 108.Ar delay 109argument, if given. 110The default interval is 5 seconds. 111.It Fl w Ar width 112Specifies the maximum width of the display. 113.\" XXX not sure for the above. 114.It Ar view 115The 116.Ar view 117argument expects to be one of: 118.Ic vmstat , 119.Ic pigs , 120.Ic ifstat , 121.Ic iostat , 122.Ic sensors , 123.Ic mbufs , 124.Ic netstat , 125.Ic swap , 126.Ic states , 127.Ic rules , 128.Ic queues , 129.Ic pf , 130.Ic pool , 131.Ic malloc , 132.Ic buckets , 133.Ic nfsclient , 134or 135.Ic nfsserver . 136These displays can also be requested interactively and are described in 137full detail below. 138.Ar view 139may be abbreviated to the minimum unambiguous prefix; 140for example, 141.Dq io 142for 143.Dq iostat . 144.It Ar delay 145The 146.Ar delay 147argument specifies the screen refresh time interval in seconds. 148This is provided for backwards compatibility, and overrides any 149interval specified with the 150.Fl s 151flag. 152The default interval is 5 seconds. 153.El 154.Pp 155Certain characters cause immediate action by 156.Nm . 157These are: 158.Bl -tag -width Fl 159.It Ic \&: 160Move the cursor to the command line and interpret the input 161line typed as a command. 162While entering a command the 163current character erase, word erase, and line kill characters 164may be used. 165.It Ic o 166Select the next ordering which sorts the rows according to a 167combination of columns. 168Available orderings depend on the view. 169Not all views support orderings. 170.It Ic p 171Pause 172.Nm . 173.It Ic q 174Quit 175.Nm . 176.It Ic r 177Reverse the selected ordering if supported by the view. 178.It Ic \&, 179Print numbers with thousand separators, where applicable. 180.It Ic ^A \*(Ba Aq Ic Home 181Jump to the beginning of the current view. 182.It Ic ^B \*(Ba Aq Ic right arrow 183Select the previous view. 184.It Ic ^E \*(Ba Aq Ic End 185Jump to the end of the current view. 186.It Ic ^F \*(Ba Aq Ic left arrow 187Select the next view. 188.It Ic ^G 189Print the name of the current 190view being shown and the refresh interval. 191.It Ic ^L 192Refresh the screen. 193.It Ic ^N \*(Ba Aq Ic down arrow 194Scroll current view down by one line. 195.It Ic ^P \*(Ba Aq Ic up arrow 196Scroll current view up by one line. 197.It Ic ^V \*(Ba Aq Ic Page Down 198Scroll current view down by one page. 199.It Ic Alt-V \*(Ba Aq Ic Page Up 200Scroll current view up by one page. 201.It Ic ^Z 202Suspend 203.Nm . 204.El 205.Pp 206The following commands are interpreted by the 207.Dq global 208command interpreter. 209.Bl -tag -width Fl 210.It Ic help 211Print the names of the available views on the command line. 212.It Ic quit 213Quit 214.Nm . 215(This may be abbreviated to 216.Ic q . ) 217.It Ic stop 218Stop refreshing the screen. 219.It Xo 220.Op Ic start 221.Op Ar number 222.Xc 223Start (continue) refreshing the screen. 224If a second, numeric, 225argument is provided it is interpreted as a refresh interval 226(in seconds). 227Supplying only a number will set the refresh interval to this 228value. 229.El 230.Pp 231.Ar view 232may be abbreviated to the minimum unambiguous prefix. 233The available views are: 234.Bl -tag -width "netstatXXX" 235.It Ic buckets 236Display kernel 237.Xr malloc 9 238bucket statistics similar to the output of 239.Cm vmstat Fl m . 240.It Ic ifstat 241Display interface statistics. 242The 243.Dq State 244column has the format 245.Sm off 246.Xo 247.Cm up \*(Ba dn 248.Bq : Cm U \*(Ba D . 249.Xc 250.Sm on 251.Sq up 252and 253.Sq dn 254represent whether the interface is up or down. 255.Sq U 256and 257.Sq D 258represent whether the interface is connected or not; 259in the case of 260.Xr carp 4 261interfaces, whether the interface is in master or backup state, respectively. 262.Pp 263The character 264.Ic B 265changes the counter view between bytes and bits. 266Pressing 267.Ic b 268displays statistics as calculated from boot time. 269.Ic r 270changes the counters to show their totals as calculated 271between display refreshes. 272.Ic t 273changes the counters to show the average per second over 274the display refresh interval; 275this is the default. 276.It Ic iostat 277Display statistics about disk throughput. 278Statistics 279on disk throughput show, for each drive, data transferred in kilobytes, 280number of disk transactions performed, and time spent in disk accesses 281(in fractions of a second). 282.It Ic malloc 283Display kernel 284.Xr malloc 9 285type statistics similar to the output of 286.Cm vmstat Fl m . 287Available orderings are: 288.Ic name , 289.Ic inuse , 290.Ic memuse , 291and 292.Ic requests . 293.It Ic mbufs 294Display mbuf usage information from kernel pools 295and mbuf cluster pool statistics of each network interface. 296.It Ic netstat 297Display network connections. 298By default, network servers awaiting requests are not displayed. 299Each address 300is displayed in the format 301.Dq host:port , 302with each shown symbolically, when possible. 303.\"It is possible to have addresses displayed numerically, 304.\"limit the display to a set of ports, hosts, and/or protocols 305.\"(the minimum unambiguous prefix may be supplied): 306.\".Bl -tag -width Ar 307.\".It Cm all 308.\"Toggle the displaying of server processes awaiting requests (this 309.\"is the equivalent of the 310.\".Fl a 311.\"flag to 312.\".Xr netstat 1 ) . 313.\".It Cm display Op Ar items 314.\"Display information about the connections associated with the 315.\"specified hosts or ports. 316.\"As for 317.\".Ar ignore , 318.\".Ar items 319.\"may be names or numbers. 320.\".It Cm ignore Op Ar items 321.\"Do not display information about connections associated with 322.\"the specified hosts or ports. 323.\"Hosts and ports may be specified 324.\"by name 325.\".Pf ( Dq vangogh , 326.\".Dq ftp ) , 327.\"or numerically. 328.\"Host addresses 329.\"use the Internet dot notation 330.\".Pq Dq 128.32.0.9 . 331.\"Multiple items 332.\"may be specified with a single command by separating them with 333.\"spaces. 334.\".It Cm names 335.\"Display network addresses symbolically. 336.\".It Cm numbers 337.\"Display network addresses numerically. 338.\".It Cm reset 339.\"Reset the port, host, and protocol matching mechanisms to the default 340.\"(any protocol, port, or host). 341.\".It Cm show Oo 342.\".Ar protocols \*(Ba ports \*(Ba hosts 343.\".Oc 344.\"Show, on the command line, the currently selected protocols, 345.\"hosts, and ports. 346.\"Protocols, hosts and ports which are being ignored are prefixed with a 347.\".Ql \&! . 348.\"If an argument is supplied to 349.\".Cm show , 350.\"then only the requested information will be displayed. 351.\".It Cm tcp \*(Ba udp \*(Ba all 352.\"Display only network connections using the indicated protocol. 353.\".El 354.It Ic nfsclient 355Display statistics about NFS client activity. 356Output resembles 357.Cm nfsstat Fl c . 358.It Ic nfsserver 359Display statistics about NFS server activity. 360Output resembles 361.Cm nfsstat Fl s . 362.It Ic pf 363Display filter information about 364.Xr pf 4 , 365similar to the output of 366.Cm pfctl Fl s Cm info 367option. 368.It Ic pigs 369Display those processes resident in main 370memory and getting the 371largest portion of the processor. 372When less than 100% of the 373processor is scheduled to user processes, the remaining time 374is accounted to the 375.Dq idle 376process. 377.It Ic pool 378Display kernel 379.Xr pool 9 380statistics similar to the output of 381.Cm vmstat Fl m . 382Available orderings are: 383.Ic name , 384.Ic requests , 385.Ic size , 386and 387.Ic number of pages . 388.It Ic queues 389Display statistics about the active 390.Xr altq 9 391queues, similar to the output of 392.Cm pfctl Fl s Cm queue . 393.It Ic rules 394Display pf rules statistics, similar to the output of 395.Cm pfctl Fl s Cm rules . 396.It Ic sensors 397Display the current values of available hardware sensors, 398in a format similar to that of 399.Xr sysctl 8 . 400.It Ic states 401Display pf states statistics, similar to the output of 402.Cm pfctl Fl s Cm states . 403Available orderings are: 404.Ic none , 405.Ic bytes , 406.Ic expiry , 407.Ic packets , 408.Ic age , 409.Ic source address , 410.Ic source port , 411.Ic destination address , 412.Ic destination port , 413.Ic rate , 414and 415.Ic peak 416columns. 417.It Ic swap 418Show information about swap space usage on all the 419swap areas compiled into the kernel. 420The first column is the device name of the partition. 421The next column is the total space available in the partition. 422The 423.Ar Used 424column indicates the total blocks used so far; 425the graph shows the percentage of space in use on each partition. 426If there is more than one swap partition in use, 427a total line is also shown. 428Areas known to the kernel but not in use are shown as not available. 429.It Ic vmstat 430Take over the entire display and show a (rather crowded) compendium 431of statistics related to virtual memory usage, process scheduling, 432device interrupts, system name translation caching, disk I/O, etc. 433This view is the default. 434.Pp 435Below the top line are statistics on memory utilization. 436The first row of the table reports memory usage only among 437active processes, that is, processes that have run in the previous 438twenty seconds. 439The second row reports on memory usage of all processes. 440The first column reports on the amount of physical memory 441claimed by processes. 442The second column reports the same figure for 443virtual memory, that is, the amount of memory that would be 444needed if all processes were resident at the same time. 445Finally, the last column shows the amount of physical memory 446on the free list. 447.Pp 448Below the memory display is a list of the average number of processes 449(over the last refresh interval) that are runnable 450.Pq Sq r , 451in disk wait other than paging 452.Pq Sq d , 453sleeping 454.Pq Sq s , 455and swapped out but desiring to run 456.Pq Sq w . 457Below the queue length listing is a numerical listing and 458a bar graph showing the amount of 459interrupt (shown as 460.Ql \*(Ba ) , 461system (shown as 462.Ql = ) , 463user (shown as 464.Ql \*(Gt ) , 465nice (shown as 466.Ql - ) , 467and idle time (shown as 468.Ql \ \& ) . 469.Pp 470To the right of the Proc display are statistics about 471Context switches 472.Pq Dq Csw , 473Traps 474.Pq Dq Trp , 475Syscalls 476.Pq Dq Sys , 477Interrupts 478.Pq Dq Int , 479Soft interrupts 480.Pq Dq Sof , 481and Faults 482.Pq Dq Flt 483which have occurred during the last refresh interval. 484.Pp 485Below the CPU usage graph are statistics on name translations. 486It lists the number of names translated in the previous interval, 487the number and percentage of the translations that were 488handled by the system wide name translation cache, and 489the number and percentage of the translations that were 490handled by the per process name translation cache. 491.Pp 492At the bottom left is the disk usage display. 493It reports the number of seeks, transfers, number 494of kilobyte blocks transferred per second averaged over the 495refresh period of the display, and 496the time spent in disk accesses. 497.Pp 498Under the date in the upper right hand quadrant are statistics 499on paging and swapping activity. 500The first two columns report the average number of pages 501brought in and out per second over the last refresh interval 502due to page faults and the paging daemon. 503The third and fourth columns report the average number of pages 504brought in and out per second over the last refresh interval 505due to swap requests initiated by the scheduler. 506The first row of the display shows the average 507number of disk transfers per second over the last refresh interval. 508The second row of the display shows the average 509number of pages transferred per second over the last refresh interval. 510.Pp 511Running down the right hand side of the display is a breakdown 512of the interrupts being handled by the system. 513At the top of the list is the total interrupts per second 514over the time interval. 515The rest of the column breaks down the total on a device 516by device basis. 517Only devices that have interrupted at least once since boot time are shown. 518.Pp 519Below the Interrupts display are 520the average number of input and output packets per second 521for all interfaces over the last refresh interval. 522.Pp 523Below the SWAPPING display and slightly to the left of the Interrupts 524display is a list of virtual memory statistics. 525The abbreviations are: 526.Pp 527.Bl -tag -compact -width "kmapentXX" -offset indent 528.It forks 529process forks 530.It fkppw 531forks where parent waits 532.It fksvm 533forks where vmspace is shared 534.It pwait 535fault had to wait on a page 536.It relck 537fault relock called 538.It rlkok 539fault relock is successful 540.It noram 541faults out of ram 542.It ndcpy 543number of times fault clears "need copy" 544.It fltcp 545number of times fault promotes with copy 546.It zfod 547fault promotes with zerofill 548.It cow 549number of times fault anon cow 550.It fmin 551min number of free pages 552.It ftarg 553target number of free pages 554.It itarg 555target number of inactive pages 556.It wired 557wired pages 558.It pdfre 559pages daemon freed since boot 560.It pdscn 561pages daemon scanned since boot 562.It pzidle 563number of zeroed pages 564.It kmapent 565number of kernel map entries 566.El 567.Pp 568The 569.Ql %zfod 570value is more interesting when observed over a long 571period, such as from boot time. 572.\"(see the 573.\".Cm boot 574.\"option below). 575.El 576.\".Pp 577.\"The following commands are specific to the 578.\".Ic vmstat 579.\"and 580.\".Ic ifstat 581.\"views; the minimum unambiguous prefix may be supplied. 582.\".Pp 583.\".Bl -tag -width Ds -compact 584.\".It Cm boot 585.\"Display cumulative statistics since the system was booted. 586.\".It Cm run 587.\"Display statistics as a running total from the point this 588.\"command is given. 589.\".It Cm time 590.\"Display statistics averaged over the refresh interval (the default). 591.\".It Cm zero 592.\"Reset running statistics to zero. 593.\".El 594.\".Pp 595.\"The following commands are common to each view which shows 596.\"information about disk drives. 597.\"These commands are used to select a set of drives to report on, 598.\"should a system have more drives configured 599.\"than can normally be displayed on the screen. 600.\".Pp 601.\".Bl -tag -width Tx -compact 602.\".It Cm display Op Ar drives 603.\"Display information about the drives indicated. 604.\"Multiple drives may be specified, separated by spaces. 605.\".It Cm ignore Op Ar drives 606.\"Do not display information about the drives indicated. 607.\"Multiple drives may be specified, separated by spaces. 608.\".El 609.Sh FILES 610.Bl -tag -width "/etc/networksXXX" -compact 611.It Pa /etc/hosts 612Host names. 613.It Pa /etc/networks 614Network names. 615.It Pa /etc/pf.conf 616.Xr pf 4 617configuration. 618.It Pa /etc/services 619Port names. 620.El 621.Sh SEE ALSO 622.Xr fstat 1 , 623.Xr kill 1 , 624.Xr netstat 1 , 625.Xr nfsstat 1 , 626.Xr ps 1 , 627.Xr top 1 , 628.Xr iostat 8 , 629.Xr pfctl 8 , 630.Xr pstat 8 , 631.Xr renice 8 , 632.Xr sysctl 8 , 633.Xr vmstat 8 634.Sh HISTORY 635The 636.Nm 637program first appeared in 638.Bx 4.3 . 639.Sh BUGS 640Certain displays presume a minimum of 80 characters per line. 641The 642.Ic vmstat 643display looks out of place because it is (it was added in as 644a separate display rather than created as a new program). 645