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