1.\" Copyright (c) 1985, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)systat.1 8.2 (Berkeley) 12/30/93 29.\" $FreeBSD: src/usr.bin/systat/systat.1,v 1.23.2.9 2002/12/29 16:35:40 schweikh Exp $ 30.\" 31.Dd October 12, 2017 32.Dt SYSTAT 1 33.Os 34.Sh NAME 35.Nm systat 36.Nd display system statistics on a crt 37.Sh SYNOPSIS 38.Nm 39.Op Fl Ar display 40.Op Ar refresh-interval 41.Sh DESCRIPTION 42The 43.Nm 44utility displays various system statistics in a screen oriented fashion 45using the curses screen display library, 46.Xr ncurses 3 . 47.Pp 48While 49.Nm 50is running the screen is usually divided into two windows (an exception 51is the 52.Ic vmstat 53and 54.Ic pvmmeter 55displays which uses the entire screen). 56The upper window depicts the current system load average. 57The information displayed in the lower window may vary, depending on 58user commands. 59The last line on the screen is reserved for user input and error messages. 60.Pp 61By default 62.Nm 63displays the processes getting the largest percentage of the processor 64in the lower window. 65Other displays show swap space usage, disk 66.Tn I/O 67statistics (a la 68.Xr iostat 8 ) , 69virtual memory statistics (a la 70.Xr vmstat 8 ) , 71network ``mbuf'' utilization, 72.Tn TCP/IP 73statistics, 74and network connections (a la 75.Xr netstat 1 ) . 76.Pp 77Input is interpreted at two different levels. 78A ``global'' command interpreter processes all keyboard input. 79If this command interpreter fails to recognize a command, the 80input line is passed to a per-display command interpreter. 81This allows each display to have certain display-specific commands. 82.Pp 83Command line options: 84.Bl -tag -width "refresh_interval" 85.It Fl Ns Ar display 86The 87.Fl 88flag expects 89.Ar display 90to be one of: 91.Ic altqs , 92.Ic icmp , 93.Ic icmp6 , 94.Ic ifstat , 95.Ic iostat , 96.Ic ip , 97.Ic ip6 , 98.Ic mbufs , 99.Ic netbw , 100.Ic netstat , 101.Ic pftop , 102.Ic pigs , 103.Ic pvmmeter , 104.Ic sensors , 105.Ic swap , 106.Ic tcp , 107or 108.Ic vmstat . 109These displays can also be requested interactively (without the 110.Sq Fl ) 111and are described in 112full detail below. 113.It Ar refresh-interval 114The 115.Ar refresh-interval 116specifies the screen refresh time interval in seconds. 117Default is 5 seconds. 118.El 119.Pp 120Certain characters cause immediate action by 121.Nm . 122These are 123.Bl -tag -width Fl 124.It Ic \&^L 125Refresh the screen. 126.It Ic \&^G 127Print the name of the current ``display'' being shown in 128the lower window and the refresh interval. 129.It Ic \&: 130Move the cursor to the command line and interpret the input 131line typed as a command. 132While entering a command the current character erase, word erase, 133and line kill characters may be used. 134.El 135.Pp 136The following commands are interpreted by the ``global'' command interpreter. 137.Bl -tag -width Fl 138.It Ic help 139Print the names of the available displays on the command line. 140.It Ic load 141Print the load average over the past 1, 5, and 15 minutes on the command line. 142.It Ic stop 143Stop refreshing the screen. 144.It Oo Ic start Oc Op Ar number 145Start (continue) refreshing the screen. 146If a second, numeric, argument is provided it is interpreted as a 147refresh interval (in seconds). 148Supplying only a number will set the refresh interval to this value. 149.It Ic quit 150Exit 151.Nm . 152(This may be abbreviated to 153.Ic q . ) 154.El 155.Pp 156The available displays are: 157.Bl -tag -width Ic 158.It Ic pigs 159Display, in the lower window, those processes resident in main 160memory and getting the 161largest portion of the processor (the default display). 162When less than 100% of the 163processor is scheduled to user processes, the remaining time 164is accounted to the ``idle'' process. 165.It Ic icmp 166Display, in the lower window, statistics about messages received and 167transmitted by the Internet Control Message Protocol 168.Pq Dq Tn ICMP . 169The left half of the screen displays information about received packets, 170and the right half displays information regarding transmitted packets. 171.Pp 172The 173.Ic icmp 174display understands two commands: 175.Ic mode 176and 177.Ic reset . 178The 179.Ic mode 180command is used to select one of four display modes, given as its argument: 181.Pp 182.Bl -tag -width absoluteXX -compact 183.It Ic rate 184Show the rate of change of each value in packets per second (the default). 185.It Ic delta 186Show the rate of change of each value in packets per refresh interval. 187.It Ic since 188Show the total change of each value since the display was last reset. 189.It Ic absolute 190Show the absolute value of each statistic. 191.El 192.Pp 193The 194.Ic reset 195command resets the baseline for 196.Ic since 197mode. 198The 199.Ic mode 200command with no argument will display the current mode in the command line. 201.It Ic icmp6 202This display is like the 203.Ic icmp 204display, but displays statistics for 205.Tn IPv6 ICMP . 206.It Ic ip 207Otherwise identical to the 208.Ic icmp 209display, except that it displays 210.Tn IP 211and 212.Tn UDP 213statistics. 214.It Ic ip6 215Like the 216.Ic ip 217display, 218except that it displays 219.Tn IPv6 220statistics. 221.It Ic tcp 222Like 223.Ic icmp , 224but with 225.Tn TCP 226statistics. 227.It Ic ifstat 228Display, in the lower window, statistics about network throughput on 229a per-interface basis. 230.It Ic iostat 231Display, in the lower window, statistics about processor use 232and disk throughput. 233Statistics on processor use appear as 234bar graphs of the amount of time executing in user mode (`user'), 235in user mode running low priority processes (`nice'), in 236system mode (`system'), in interrupt mode (`interrupt'), 237and idle (`idle'). 238Statistics on disk throughput show, for each drive, megabytes per second, 239average number of disk transactions per second, and 240average kilobytes of data per transaction. 241This information may be 242displayed as bar graphs or as rows of numbers which scroll downward. 243Bar graphs are shown by default. 244.Pp 245The following commands are specific to the 246.Ic iostat 247display; the minimum unambiguous prefix may be supplied. 248.Pp 249.Bl -tag -width Fl -compact 250.It Ic numbers 251Show the disk 252.Tn I/O 253statistics in numeric form. 254Values are displayed in numeric columns which scroll downward. 255.It Ic bars 256Show the disk 257.Tn I/O 258statistics in bar graph form (default). 259.It Ic kbpt 260Toggle the display of kilobytes per transaction. 261(the default is to not display kilobytes per transaction). 262.El 263.It Ic sensors 264Display, in the lower window, 265the current values of available hardware sensors, 266in a format similar to that of 267.Xr sysctl 8 . 268.Pp 269The following commands are specific to the 270.Ic sensors 271display; the minimum unambiguous prefix may be supplied. 272.Pp 273.Bl -tag -width Fl -compact 274.It Ic type Op Ar type ... 275Display only the sensors which match the specified 276.Ar type . 277Multiple types may be specified, 278separated by spaces. 279If no types are specified, 280all available sensors will be displayed. 281Supported values of 282.Ar type 283are 284.Cm temp , 285.Cm fan , 286.Cm volt , 287.Cm acvolt , 288.Cm resistance , 289.Cm power , 290.Cm current , 291.Cm watthour , 292.Cm amphour , 293.Cm indicator , 294.Cm raw , 295.Cm percent , 296.Cm illuminance , 297.Cm drive , 298.Cm timedelta , 299and 300.Cm ecc . 301.It Ic match Op Ar device ... 302Display only the sensors match the specified 303.Ar device . 304Multiple devices may be specified, 305separated by spaces. 306If no devices are specified, 307all available sensors will be displayed. 308A device type could be specified by using 309an asterisk 310.Pq Sq Li * 311in the place of the device unit. 312For example: 313.Pp 314.Dl match cpu* 315.El 316.It Ic swap 317Show information about swap space usage on all the 318swap areas compiled into the kernel. 319The first column is the device name of the partition. 320The next column is the total space available in the partition. 321The `Used' column indicates the total blocks used so far; 322the graph shows the percentage of space in use on each partition. 323If there are more than one swap partition in use, 324a total line is also shown. 325Areas known to the kernel, but not in use are shown as not available. 326.It Ic mbufs 327Display, in the lower window, the number of mbufs allocated 328for particular uses, i.e.\& data, socket structures, etc. 329.It Ic vmstat 330Take over the entire display and show a (rather crowded) compendium 331of statistics related to virtual memory usage, process scheduling, 332device interrupts, system name translation cacheing, disk 333.Tn I/O 334etc. 335.Pp 336The upper left quadrant of the screen shows the number 337of users logged in and the load average over the last one, five, 338and fifteen minute intervals. 339.Pp 340Below this line are statistics on memory utilization. 341The first row (`Active') reports memory usage in bytes 342only among active processes, 343that is processes that have run in the previous twenty seconds. 344The second row (`Kernel') reports memory usage in bytes by the kernel. 345The third row (`Free .. i+c+f') shows freeable memory in bytes, 346which is inactive + cache + free. 347I.e.\& Free i+c+f includes inactive pages, which aren't quite free, 348but they will be made free given enough memory pressure. 349Finally the last row (`Total') shows total system memory in bytes. 350The second column reports on memory usage of all processes. 351The first row (`VM-rss') shows bytes for total RSS. 352This is basically how many pages the system is mapping to user processes. 353Due to sharing this can be a large value. 354The second row (`VM-swp') reports on swap, first swap used in bytes, 355then, after `/', total swap in bytes. 356.Pp 357Below the memory display is a list of the 358average number of processes (over the last refresh interval) 359that are runnable (`r'), in page wait (`p'), 360in disk wait other than paging (`d'), 361sleeping (`s'), and swapped out but desiring to run (`w'). 362The row also shows the average number of context switches (`Csw'), 363traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'), 364network software interrupts (`Sof'), and page faults (`Flt'). 365.Pp 366Below the process queue length listing is a listing of 367.Tn CPU 368usage, a numerical listing and a bar graph showing the amount of 369system (`='), interrupt (`+'), user (`>'), nice (`-'), and idle time (` '). 370.Pp 371Below the 372.Tn CPU 373usage display are statistics on name translations and execs. 374It lists the number of path names translated 375in the previous interval (`Path-lookups'), 376the number and percentage of the path lookups that were 377handled by the name translation cache, 378the average number of path components in path lookups (`Components') and, 379the number of execs 380.Xr ( execve 2 ) 381per second (`Execs'). 382.Pp 383At the bottom left is the disk usage display. 384It reports the number of 385kilobytes per transaction (`KB/t'), 386read transactions per second (`tpr/s'), 387megabytes per second in read transaction (`MBr/s'), 388write transactions per second (`tpw/s'), 389megabytes per second in write transaction (`MBw/s') and 390the percentage of the time the disk was busy (`% busy') averaged 391over the refresh period of the display (by default, five seconds). 392The system keeps statistics on most every storage device. 393In general, up to seven devices are displayed. 394The devices displayed by default are the 395first devices in the kernel's device list. 396Some devices are not shown by default, see 397.Ic ignore 398command below. 399See 400.Xr devstat 3 401and 402.Xr devstat 9 403for details on the devstat system. 404.Pp 405If at most 4 disk devices are shown, 406extended virtual memory statistics are shown right to disk usage: 407pages non-optimized zero filled on demand (`nzfod'), 408pages optimized zero filled on demand (`ozfod'), 409slow (i.e.\& non-optimized) zero fills percentage (`%sloz'), 410total pages freed (`tfree'). 411.Pp 412Under the date in the upper right hand quadrant are statistics 413on paging and swapping activity. 414The first two columns (`VN PAGER') report the average number of bytes 415brought in and out per second over the last refresh interval 416due to page faults and the paging daemon. 417The third and fourth columns (`SWAP PAGER') report the average number of bytes 418brought in and out per second over the last refresh interval 419due to swap requests initiated by the scheduler. 420The first row (`bytes') of the display shows the average 421number of bytes transferred per second over the last refresh interval; 422the second row (`count') of the display shows the average 423number of disk transfers per second over the last refresh interval; 424this usually matches number of pages transferred 425per second over the last refresh interval. 426.Pp 427Below the paging statistics is a column of lines regarding the virtual 428memory system which list the average number of 429bytes in pages zero filled on demand (`zfod') 430(shown with extended virtual memory statistics if screen space permits), 431bytes in pages copied on write (`cow'), 432bytes in pages wired down (`wire'), 433bytes in active pages (`act'), 434bytes in inactive pages (`inact'), 435bytes in pages on the buffer cache queue (`cache'), 436bytes in free pages (`free'), 437pages freed by the page daemon (`daefr'), 438pages freed by exiting processes (`prcfr'), 439pages reactivated from the free list (`react'), 440times the page daemon was awakened (`pdwak'), 441pages analyzed by the page daemon (`pdpgs'), 442and 443intransit blocking page faults (`intrn') 444per second over the refresh interval. 445.Pp 446At the bottom of this column are lines showing the 447amount of memory, in bytes, used for the buffer cache (`buf'), 448number of dirty buffers in the buffer cache (`dirtybuf'), 449number of active vnodes (`activ-vp'), 450number of cached vnodes (`cachd-vp'), 451and 452number of inactive vnodes (`inact-vp'). 453.Pp 454Running down the right hand side of the display is a breakdown 455of the interrupts being handled by the system (`Interrupts'). 456At the top of the list is the total interrupts per second 457over the time interval (`total'). 458The rest of the column breaks down the total on a device by device basis. 459Only devices that have interrupted at least once since boot time are shown. 460.Pp 461The following commands are specific to the 462.Ic vmstat 463display; the minimum unambiguous prefix may be supplied. 464.Pp 465.Bl -tag -width Ar -compact 466.It Ic boot 467Display cumulative statistics since the system was booted. 468.It Ic run 469Display statistics as a running total from the point this command is given. 470.It Ic time 471Display statistics averaged over the refresh interval (the default). 472.It Ic zero 473Reset running statistics to zero. 474.El 475.It Ic pvmmeter 476Display total and per 477.Tn CPU 478statistics, including 479.Tn LAPIC 480timer interrupts (`timer'), 481.Tn IPIs 482(Inter-Processor Interrupts) (`ipi'), 483external interrupts (i.e.\& not timer or ipi) (`extint'), 484.Tn CPU 485time breakdown (`user%', `sys%', `intr%', and `idle%'), 486.Tn SMP 487collisions (`smpcol'), and name of last colliding item (`label'). 488Item can be 489.Xr token 9 , 490.Xr lockmgr 9 , 491.Xr mutex 9 , 492or 493.Xr spinlock 9 . 494.It Ic netstat 495Display, in the lower window, network connections. 496By default, network servers awaiting requests are not displayed. 497Each address is displayed in the format ``host.port'', 498with each shown symbolically, when possible. 499It is possible to have addresses displayed numerically, 500limit the display to a set of ports, hosts, and/or protocols 501(the minimum unambiguous prefix may be supplied): 502.Pp 503.Bl -tag -width Ar -compact 504.It Ic all 505Toggle the displaying of server processes awaiting requests (this 506is the equivalent of the 507.Fl a 508flag to 509.Xr netstat 1 ) . 510.It Ic numbers 511Display network addresses numerically. 512.It Ic names 513Display network addresses symbolically. 514.It Ic proto Ar protocol 515Display only network connections using the indicated 516.Ar protocol . 517Supported protocols are 518.Cm tcp , 519.Cm udp , 520and 521.Cm all . 522.It Ic ignore Op Ar items 523Do not display information about connections associated with 524the specified hosts or ports. 525Hosts and ports may be specified 526by name (``vangogh'', ``ftp''), or numerically. 527Host addresses use the Internet dot notation (``128.32.0.9''). 528Multiple items 529may be specified with a single command by separating them with spaces. 530.It Ic display Op Ar items 531Display information about the connections associated with the 532specified hosts or ports. 533As for 534.Ic ignore , 535.Ar items 536may be names or numbers. 537.It Ic show Op Cm ports | protos | hosts 538Show, on the command line, the currently selected protocols, hosts, and ports. 539Hosts and ports which are being ignored are prefixed with a `!'. 540If 541.Cm ports 542or 543.Cm hosts 544is supplied as an argument to 545.Ic show , 546then only the requested information will be displayed. 547.It Ic reset 548Reset the port, host, and protocol matching mechanisms to the default 549(any protocol, port, or host). 550.El 551.It Ic netbw 552Display aggregate and per-connection TCP receive and transmit rates. 553Only active TCP connections originated or terminated by the host 554are shown. 555.It Ic pftop 556Display packet filter 557.Pq Xr pf 4 558state information for states which are 559actively passing data. 560This requires 561.Xr pf 4 562to be active to be meaningful 563but is capable of displaying connection state for all packet traffic 564passing through the machine, even for connections that do not originate 565or terminate on the machine. 566.Pp 567You need a wide ~100 column window to display 568.Ic pftop 569reasonably well. 570IPV6 addresses are truncated (just the first two and last two words 571are displayed) for brevity. 572Generally speaking `rcv' is data received 573by the first IP address and `snd' is data sent to the second IP address. 574`ttl' is 575the total sum of data sent plus received tracked by the state. 576.Pp 577The display is sorted by average rx+tx bandwidth calculated on a 1/8 decay 578curve to prevent fields from jumping around too much. 579Units for all rows 580are selected based on the largest bandwidth measurement for uniformity. 581Note that two states will be present for any connection operating over NAT. 582Needs root privilege. 583.It Ic altqs 584Display packet filter altq statistics. 585The ALTQ operates in conjunction with the packet filter (pf) on the 586interface's transmit path. 587Packet rate, data rate in bytes per interval, drop rate, and queue 588length is displayed in three separate sections in a convenient 589INTERFACE-by-ALTQLABEL matrix. 590.Pp 591To save space drops 592and queue length are combined in the third section. 593If packet drops are present, drops 594will be displayed, otherwise the packet queue length with a 595.Ql Q 596suffix will be displayed. 597.El 598.Pp 599Commands to switch between displays may be abbreviated to the 600minimum unambiguous prefix; for example, ``io'' for ``iostat''. 601Certain information may be discarded when the screen size is 602insufficient for display. 603For example, on a machine with 10 drives the 604.Ic iostat 605bar graph displays only 3 drives on a 24 line terminal. 606When a bar graph would overflow the allotted screen space it is 607truncated and the actual value is printed ``over top'' of the bar. 608.Pp 609The following commands are common to each display which shows 610information about disk drives. 611These commands are used to 612select a set of drives to report on, should your system have 613more drives configured than can normally be displayed on the screen. 614.Pp 615.Bl -tag -width Ar -compact 616.It Ic ignore Op Ar drives 617Do not display information about the drives indicated. 618Multiple drives may be specified, separated by spaces. 619.Pp 620By default 621.Xr md 4 , 622.Xr pass 4 , 623and 624.Xr sg 4 625devices are 626.Ic ignore Ns d . 627This is to save space for other devices which are usually more interesting. 628.It Ic display Op Ar drives 629Display information about the drives indicated. 630Multiple drives may be specified, separated by spaces. 631.It Ic only Op Ar drives 632Display only the specified drives. 633Multiple drives may be specified, separated by spaces. 634.It Ic drives 635Display a list of available devices. 636.It Ic match Ar type , Ns Ar if , Ns Ar pass Op | Ar ... 637Display devices matching the given pattern. 638The basic matching expressions are the same as those used in 639.Xr iostat 8 640with one difference. 641Instead of specifying multiple 642.Fl t 643arguments which are then ORed together, the user instead specifies multiple 644matching expressions joined by the pipe 645.Pq Ql \&| 646character. 647The comma separated arguments within each matching expression are ANDed 648together, and then the pipe separated matching expressions are ORed together. 649Any device matching the combined expression will be displayed, 650if there is room to display it. 651For example: 652.Pp 653.Dl match da,scsi | cd,ide 654.Pp 655This will display all 656.Tn SCSI 657Direct Access devices and all 658.Tn IDE CDROM 659devices. 660.Pp 661.Dl match da | sa | cd,pass 662.Pp 663This will display all Direct Access devices, all Sequential Access devices, 664and all passthrough devices that provide access to 665.Tn CDROM 666drives. 667.El 668.Sh FILES 669.Bl -tag -width ".Pa /boot/kernel/kernel" -compact 670.It Pa /boot/kernel/kernel 671For the namelist 672.It Pa /dev/kmem 673For information in main memory 674.It Pa /etc/hosts 675For host names 676.It Pa /etc/networks 677For network names 678.It Pa /etc/services 679For port names 680.El 681.Sh SEE ALSO 682.Xr netstat 1 , 683.Xr devstat 3 , 684.Xr kvm 3 , 685.Xr icmp 4 , 686.Xr icmp6 4 , 687.Xr ip 4 , 688.Xr ip6 4 , 689.Xr pf 4 , 690.Xr tcp 4 , 691.Xr udp 4 , 692.Xr iostat 8 , 693.Xr sysctl 8 , 694.Xr vmstat 8 , 695.Xr devstat 9 , 696.Xr lockmgr 9 , 697.Xr mutex 9 , 698.Xr spinlock 9 , 699.Xr token 9 700.Sh HISTORY 701The 702.Nm 703program appeared in 704.Bx 4.3 . 705The 706.Ic icmp , 707.Ic ip , 708and 709.Ic tcp 710displays appeared in 711.Fx 3.0 ; 712the notion of having different display modes for the 713.Tn ICMP , 714.Tn IP , 715.Tn TCP , 716and 717.Tn UDP 718statistics was stolen from the 719.Fl C 720option to 721.Xr netstat 1 722in Silicon Graphics' 723.Tn IRIX 724system. 725.Sh BUGS 726Certain displays presume a minimum of 80 characters per line. 727The 728.Ic vmstat 729display looks out of place because it is (it was added in as 730a separate display rather than created as a new program). 731