1.\" $OpenBSD: systat.1,v 1.99 2014/10/24 10:18:50 schwarze 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: October 24 2014 $ 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 aBbiNn 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. 91The default is to exit after two screen updates, 92with statistics only ever displayed once. 93Useful for views such as 94.Ic cpu , 95where initial calculations are useless. 96.It Fl b 97Raw, non-interactive mode. 98The default is to exit after one screen update, 99with statistics displayed every update. 100.It Fl d Ar count 101Exit after 102.Ar count 103screen updates. 104.It Fl i 105Interactive mode. 106.It Fl N 107Resolve network addresses to names. 108This is the opposite of the 109.Fl n 110option. 111.It Fl n 112Do not try to reverse map IP addresses. 113This is the default. 114.It Fl s Ar delay 115Specifies the screen refresh time interval in seconds. 116This option is overridden by the final 117.Ar delay 118argument, if given. 119The default interval is 5 seconds. 120.It Fl w Ar width 121Specifies the maximum width of the output in raw, non-interactive mode. 122.It Ar view 123The 124.Ar view 125argument expects to be one of: 126.Ic vmstat , 127.Ic pigs , 128.Ic ifstat , 129.Ic iostat , 130.Ic sensors , 131.Ic mbufs , 132.Ic netstat , 133.Ic swap , 134.Ic states , 135.Ic rules , 136.Ic queues , 137.Ic pf , 138.Ic pool , 139.Ic malloc , 140.Ic buckets , 141.Ic nfsclient , 142.Ic nfsserver , 143or 144.Ic cpu . 145These displays can also be requested interactively and are described in 146full detail below. 147.Ar view 148may be abbreviated to the minimum unambiguous prefix; 149for example, 150.Dq io 151for 152.Dq iostat . 153.It Ar delay 154The 155.Ar delay 156argument specifies the screen refresh time interval in seconds. 157This is provided for backwards compatibility, and overrides any 158interval specified with the 159.Fl s 160flag. 161The default interval is 5 seconds. 162.El 163.Pp 164Certain characters cause immediate action by 165.Nm . 166These are: 167.Bl -tag -width Fl 168.It Ic \&: 169Move the cursor to the command line and interpret the input 170line typed as a command. 171While entering a command the 172current character erase, word erase, and line kill characters 173may be used. 174.It Ic o 175Select the next ordering which sorts the rows according to a 176combination of columns. 177Available orderings depend on the view. 178Not all views support orderings. 179.It Ic p 180Pause 181.Nm . 182.It Ic q 183Quit 184.Nm . 185.It Ic r 186Reverse the selected ordering if supported by the view. 187.It Ic \&, 188Print numbers with thousand separators, where applicable. 189.It Ic ^A \*(Ba Aq Ic Home 190Jump to the beginning of the current view. 191.It Ic ^B \*(Ba Aq Ic right arrow 192Select the previous view. 193.It Ic ^E \*(Ba Aq Ic End 194Jump to the end of the current view. 195.It Ic ^F \*(Ba Aq Ic left arrow 196Select the next view. 197.It Ic ^G 198Print the name of the current 199view being shown and the refresh interval. 200.It Ic ^L 201Refresh the screen. 202.It Ic ^N \*(Ba Aq Ic down arrow 203Scroll current view down by one line. 204.It Ic ^P \*(Ba Aq Ic up arrow 205Scroll current view up by one line. 206.It Ic ^V \*(Ba Aq Ic Page Down 207Scroll current view down by one page. 208.It Ic Alt-V \*(Ba Aq Ic Page Up 209Scroll current view up by one page. 210.It Ic ^Z 211Suspend 212.Nm . 213.El 214.Pp 215The following commands are interpreted by the 216.Dq global 217command interpreter. 218.Bl -tag -width Fl 219.It Ic help 220Print the names of the available views on the command line. 221.It Ic quit 222Quit 223.Nm . 224(This may be abbreviated to 225.Ic q . ) 226.It Ic stop 227Stop refreshing the screen. 228.It Xo 229.Op Ic start 230.Op Ar number 231.Xc 232Start (continue) refreshing the screen. 233If a second, numeric, 234argument is provided it is interpreted as a refresh interval 235(in seconds). 236Supplying only a number will set the refresh interval to this 237value. 238.El 239.Pp 240.Ar view 241may be abbreviated to the minimum unambiguous prefix. 242The available views are: 243.Bl -tag -width "netstatXXX" 244.It Ic buckets 245Display kernel 246.Xr malloc 9 247bucket statistics similar to the output of 248.Cm vmstat Fl m . 249.It Ic cpu 250Display information about the average usage of each CPU, 251similar to the output provided by 252.Xr top 1 . 253.It Ic ifstat 254Display interface statistics. 255The 256.Dq State 257column has the format 258.Sm off 259.Xo 260.Cm up \*(Ba dn 261.Bq : Cm U \*(Ba D . 262.Xc 263.Sm on 264.Sq up 265and 266.Sq dn 267represent whether the interface is up or down. 268.Sq U 269and 270.Sq D 271represent whether the interface is connected or not; 272in the case of 273.Xr carp 4 274interfaces, whether the interface is in master or backup state, respectively. 275.Pp 276The character 277.Ic B 278changes the counter view between bytes and bits. 279Pressing 280.Ic b 281displays statistics as calculated from boot time. 282.Ic r 283changes the counters to show their totals as calculated 284between display refreshes. 285.Ic t 286changes the counters to show the average per second over 287the display refresh interval; 288this is the default. 289.It Ic iostat 290Display statistics about disk throughput. 291Statistics 292on disk throughput show, for each drive, data transferred in kilobytes, 293number of disk transactions performed, and time spent in disk accesses 294(in fractions of a second). 295.It Ic malloc 296Display kernel 297.Xr malloc 9 298type statistics similar to the output of 299.Cm vmstat Fl m . 300Available orderings are: 301.Ic name , 302.Ic inuse , 303.Ic memuse , 304and 305.Ic requests . 306.It Ic mbufs 307Display mbuf usage information from kernel pools 308and mbuf cluster pool statistics of each network interface. 309.It Ic netstat 310Display network connections. 311Each address 312is displayed numerically in the format 313.Dq host:port . 314By default, network servers awaiting requests are not displayed. 315It is also possible to have addresses displayed symbolically, 316when possible, and limit the display to a set of protocols 317(the minimum unambiguous prefix may be supplied): 318.Bl -tag -width Ar 319.It Cm all 320Toggle the displaying of server processes awaiting requests (this 321is the equivalent of the 322.Fl a 323flag to 324.Xr netstat 1 ) . 325.It Cm names 326Display network addresses symbolically. 327.It Cm numbers 328Display network addresses numerically. 329.It Cm reset 330Reset matching mechanisms to the default. 331.\".It Cm show Oo 332.\".Ar protocols \*(Ba ports \*(Ba hosts 333.\".Oc 334.\"Show, on the command line, the currently selected protocols, 335.\"hosts, and ports. 336.\"Protocols, hosts and ports which are being ignored are prefixed with a 337.\".Ql \&! . 338.\"If an argument is supplied to 339.\".Cm show , 340.\"then only the requested information will be displayed. 341.It Cm tcp \*(Ba udp 342Display only network connections using the indicated protocol. 343.El 344.It Ic nfsclient 345Display statistics about NFS client activity. 346Output resembles 347.Cm nfsstat Fl c . 348.It Ic nfsserver 349Display statistics about NFS server activity. 350Output resembles 351.Cm nfsstat Fl s . 352.It Ic pf 353Display filter information about 354.Xr pf 4 , 355similar to the output of 356.Cm pfctl Fl s Cm info 357option. 358.It Ic pigs 359Display those processes resident in main 360memory and getting the 361largest portion of the processor. 362When less than 100% of the 363processor is scheduled to user processes, the remaining time 364is accounted to the 365.Dq idle 366process. 367.It Ic pool 368Display kernel 369.Xr pool 9 370statistics similar to the output of 371.Cm vmstat Fl m . 372Available orderings are: 373.Ic name , 374.Ic requests , 375.Ic size , 376and 377.Ic number of pages . 378.Pp 379By default only the statistics of active pools are displayed but pressing 380.Ic A 381changes the view to show all of them. 382.It Ic queues 383Display statistics about the active queues, 384similar to the output of 385.Cm pfctl Fl s Cm queue . 386.It Ic rules 387Display pf rules statistics, similar to the output of 388.Cm pfctl Fl s Cm rules . 389.It Ic sensors 390Display the current values of available hardware sensors, 391in a format similar to that of 392.Xr sysctl 8 . 393.It Ic states 394Display pf states statistics, similar to the output of 395.Cm pfctl Fl s Cm states . 396Available orderings are: 397.Ic none , 398.Ic bytes , 399.Ic expiry , 400.Ic packets , 401.Ic age , 402.Ic source address , 403.Ic source port , 404.Ic destination address , 405.Ic destination port , 406.Ic rate , 407and 408.Ic peak 409columns. 410.It Ic swap 411Show information about swap space usage on all the 412swap areas compiled into the kernel. 413The first column is the device name of the partition. 414The next column is the total space available in the partition. 415The 416.Ar Used 417column indicates the total blocks used so far; 418the graph shows the percentage of space in use on each partition. 419If there is more than one swap partition in use, 420a total line is also shown. 421Areas known to the kernel but not in use are shown as not available. 422.It Ic vmstat 423Take over the entire display and show a (rather crowded) compendium 424of statistics related to virtual memory usage, process scheduling, 425device interrupts, system name translation caching, disk I/O, etc. 426This view is the default. 427.Pp 428Below the top line are statistics on memory utilization. 429The first row of the table reports memory usage only among 430active processes, that is, processes that have run in the previous 431twenty seconds. 432The second row reports on memory usage of all processes. 433The first column reports on the amount of physical memory 434claimed by processes. 435The second column reports the same figure for 436virtual memory, that is, the amount of memory that would be 437needed if all processes were resident at the same time. 438Finally, the last column shows the amount of physical memory 439on the free list. 440.Pp 441Below the memory display is a list of the average number of processes 442(over the last refresh interval) that are runnable 443.Pq Sq r , 444in disk wait other than paging 445.Pq Sq d , 446sleeping 447.Pq Sq s , 448and swapped out but desiring to run 449.Pq Sq w . 450Below the queue length listing is a numerical listing and 451a bar graph showing the amount of 452interrupt (shown as 453.Ql \*(Ba ) , 454system (shown as 455.Ql = ) , 456user (shown as 457.Ql \*(Gt ) , 458nice (shown as 459.Ql - ) , 460and idle time (shown as 461.Ql \ \& ) . 462.Pp 463To the right of the Proc display are statistics about 464Context switches 465.Pq Dq Csw , 466Traps 467.Pq Dq Trp , 468Syscalls 469.Pq Dq Sys , 470Interrupts 471.Pq Dq Int , 472Soft interrupts 473.Pq Dq Sof , 474and Faults 475.Pq Dq Flt 476which have occurred during the last refresh interval. 477.Pp 478Below the CPU usage graph are statistics on name translations. 479It lists the number of names translated in the previous interval, 480the number and percentage of the translations that were 481handled by the system wide name translation cache, and 482the number and percentage of the translations that were 483handled by the per process name translation cache. 484.Pp 485At the bottom left is the disk usage display. 486It reports the number of seeks, transfers, number 487of kilobyte blocks transferred per second averaged over the 488refresh period of the display, and 489the time spent in disk accesses. 490.Pp 491Under the date in the upper right hand quadrant are statistics 492on paging and swapping activity. 493The first two columns report the average number of pages 494brought in and out per second over the last refresh interval 495due to page faults and the paging daemon. 496The third and fourth columns report the average number of pages 497brought in and out per second over the last refresh interval 498due to swap requests initiated by the scheduler. 499The first row of the display shows the average 500number of disk transfers per second over the last refresh interval. 501The second row of the display shows the average 502number of pages transferred per second over the last refresh interval. 503.Pp 504Running down the right hand side of the display is a breakdown 505of the interrupts being handled by the system. 506At the top of the list is the total interrupts per second 507over the time interval. 508The rest of the column breaks down the total on a device 509by device basis. 510Only devices that have interrupted at least once since boot time are shown. 511.Pp 512Below the Interrupts display are 513the average number of input and output packets per second 514for all interfaces over the last refresh interval. 515.Pp 516Below the SWAPPING display and slightly to the left of the Interrupts 517display is a list of virtual memory statistics. 518The abbreviations are: 519.Pp 520.Bl -tag -compact -width "kmapentXX" -offset indent 521.It forks 522process forks 523.It fkppw 524forks where parent waits 525.It fksvm 526forks where vmspace is shared 527.It pwait 528fault had to wait on a page 529.It relck 530fault relock called 531.It rlkok 532fault relock is successful 533.It noram 534faults out of ram 535.It ndcpy 536number of times fault clears "need copy" 537.It fltcp 538number of times fault promotes with copy 539.It zfod 540fault promotes with zerofill 541.It cow 542number of times fault anon cow 543.It fmin 544min number of free pages 545.It ftarg 546target number of free pages 547.It itarg 548target number of inactive pages 549.It wired 550wired pages 551.It pdfre 552pages daemon freed since boot 553.It pdscn 554pages daemon scanned since boot 555.It pzidle 556number of zeroed pages 557.It kmapent 558number of kernel map entries 559.El 560.El 561.\".Pp 562.\"The following commands are specific to the 563.\".Ic vmstat 564.\"and 565.\".Ic ifstat 566.\"views; the minimum unambiguous prefix may be supplied. 567.\".Pp 568.\".Bl -tag -width Ds -compact 569.\".It Cm boot 570.\"Display cumulative statistics since the system was booted. 571.\".It Cm run 572.\"Display statistics as a running total from the point this 573.\"command is given. 574.\".It Cm time 575.\"Display statistics averaged over the refresh interval (the default). 576.\".It Cm zero 577.\"Reset running statistics to zero. 578.\".El 579.\".Pp 580.\"The following commands are common to each view which shows 581.\"information about disk drives. 582.\"These commands are used to select a set of drives to report on, 583.\"should a system have more drives configured 584.\"than can normally be displayed on the screen. 585.\".Pp 586.\".Bl -tag -width Tx -compact 587.\".It Cm display Op Ar drives 588.\"Display information about the drives indicated. 589.\"Multiple drives may be specified, separated by spaces. 590.\".It Cm ignore Op Ar drives 591.\"Do not display information about the drives indicated. 592.\"Multiple drives may be specified, separated by spaces. 593.\".El 594.Sh FILES 595.Bl -tag -width "/etc/servicesXXX" -compact 596.It Pa /etc/hosts 597Host names. 598.It Pa /etc/pf.conf 599.Xr pf 4 600configuration. 601.It Pa /etc/services 602Port names. 603.El 604.Sh SEE ALSO 605.Xr fstat 1 , 606.Xr kill 1 , 607.Xr netstat 1 , 608.Xr nfsstat 1 , 609.Xr ps 1 , 610.Xr top 1 , 611.Xr iostat 8 , 612.Xr pfctl 8 , 613.Xr pstat 8 , 614.Xr renice 8 , 615.Xr sysctl 8 , 616.Xr vmstat 8 617.Sh HISTORY 618The 619.Nm 620program first appeared in 621.Bx 4.3 . 622.Sh BUGS 623Certain displays presume a minimum of 80 characters per line. 624The 625.Ic vmstat 626display looks out of place because it is (it was added in as 627a separate display rather than created as a new program). 628