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$ 30.\" 31.Dd April 1, 2022 32.Dt SYSTAT 1 33.Os 34.Sh NAME 35.Nm systat 36.Nd display system statistics 37.Sh SYNOPSIS 38.Nm 39.Op Fl Ar display 40.Op Ar display-commands 41.Op Ar refresh-interval 42.Sh DESCRIPTION 43The 44.Nm 45utility displays various system statistics in a screen oriented fashion 46using the curses screen display library, 47.Xr ncurses 3 . 48.Pp 49While 50.Nm 51is running the screen is usually divided into two windows (an exception 52is the vmstat display which uses the entire screen). 53The 54upper window depicts the current system load average. 55The 56information displayed in the lower window may vary, depending on 57user commands. 58The last line on the screen is reserved for user 59input 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 I/O statistics (a la 66.Xr iostat 8 ) , 67virtual memory statistics (a la 68.Xr vmstat 8 ) , 69TCP/IP statistics, 70and network connections (a la 71.Xr netstat 1 ) . 72.Pp 73Input is interpreted at two different levels. 74A ``global'' command interpreter processes all keyboard input. 75If this command interpreter fails to recognize a command, the 76input line is passed to a per-display command interpreter. 77This 78allows each display to have certain display-specific commands. 79.Pp 80Command line options: 81.Bl -tag -width "refresh_interval" 82.It Fl Ns Ar display 83The 84.Fl 85flag expects 86.Ar display 87to be one of: 88.Ic icmp , 89.Ic icmp6 , 90.Ic ifstat , 91.Ic iolat , 92.Ic iostat , 93.Ic ip , 94.Ic ip6 , 95.Ic netstat , 96.Ic pigs , 97.Ic sctp , 98.Ic swap , 99.Ic tcp , 100.Ic vmstat , 101or 102.Ic zarc , 103These displays can also be requested interactively (without the 104.Dq Fl ) 105and are described in 106full detail below. 107.It Ar refresh-interval 108The 109.Ar refresh-value 110specifies the screen refresh time interval in seconds. 111Time interval can be fractional. 112.It Ar display-commands 113A list of commands specific to this display. 114These commands can also be entered interactively and are described for 115each display separately below. 116If the command requires arguments, they can be specified as separate 117command line arguments. 118A command line argument 119.Fl - 120will finish display commands. 121For example: 122.Pp 123.Dl Nm Fl ifstat Fl match Ar bge0,em1 Fl pps 124.Pp 125This will display statistics of packets per second for network interfaces 126named as bge0 and em1. 127.Pp 128.Dl Nm Fl iostat Fl numbers Fl - Ar 2.1 129.Pp 130This will display all IO statistics in a numeric format and the information 131will be refreshed each 2.1 seconds. 132.El 133.Pp 134Certain characters cause immediate action by 135.Nm . 136These are 137.Bl -tag -width Fl 138.It Ic \&^L 139Refresh the screen. 140.It Ic \&^G 141Print the name of the current ``display'' being shown in 142the lower window and the refresh interval. 143.It Ic \&: 144Move the cursor to the command line and interpret the input 145line typed as a command. 146While entering a command the 147current character erase, word erase, and line kill characters 148may be used. 149.El 150.Pp 151The following commands are interpreted by the ``global'' 152command interpreter. 153.Bl -tag -width Fl 154.It Ic help 155Print the names of the available displays on the command line. 156.It Ic load 157Print the load average over the past 1, 5, and 15 minutes 158on the command line. 159.It Ic stop 160Stop refreshing the screen. 161.It Xo 162.Op Ic start 163.Op Ar number 164.Xc 165Start (continue) refreshing the screen. 166If a second, numeric, 167argument is provided it is interpreted as a refresh interval 168(in seconds). 169Supplying only a number will set the refresh interval to this 170value. 171.It Ic quit 172Exit 173.Nm . 174(This may be abbreviated to 175.Ic q . ) 176.El 177.Pp 178The available displays are: 179.Bl -tag -width Ic 180.It Ic pigs 181Display, in the lower window, those processes resident in main 182memory and getting the 183largest portion of the processor (the default display). 184When less than 100% of the 185processor is scheduled to user processes, the remaining time 186is accounted to the ``idle'' process. 187.It Ic icmp 188Display, in the lower window, statistics about messages received and 189transmitted by the Internet Control Message Protocol 190.Pq Dq ICMP . 191The left half of the screen displays information about received 192packets, and the right half displays information regarding transmitted 193packets. 194.Pp 195The 196.Ic icmp 197display understands two commands: 198.Ic mode 199and 200.Ic reset . 201The 202.Ic mode 203command is used to select one of four display modes, given as its argument: 204.Bl -tag -width absoluteXX -compact 205.It Ic rate : 206show the rate of change of each value in packets (the default) 207per second 208.It Ic delta : 209show the rate of change of each value in packets per refresh interval 210.It Ic since : 211show the total change of each value since the display was last reset 212.It Ic absolute : 213show the absolute value of each statistic 214.El 215.Pp 216The 217.Ic reset 218command resets the baseline for 219.Ic since 220mode. 221The 222.Ic mode 223command with no argument will display the current mode in the command 224line. 225.It Ic icmp6 226This display is like the 227.Ic icmp 228display, 229but displays statistics for IPv6 ICMP. 230.It Ic ip 231Otherwise identical to the 232.Ic icmp 233display, except that it displays IP and UDP statistics. 234.It Ic ip6 235Like the 236.Ic ip 237display, 238except that it displays IPv6 statistics. 239It does not display UDP statistics. 240.It Ic sctp 241Like 242.Ic icmp , 243but with SCTP statistics. 244.It Ic tcp 245Like 246.Ic icmp , 247but with TCP statistics. 248.It Ic iolat 249Display statistics describing the hardware latencies of I/O operations as 250computed by the 251.Va CAM_IOSCHED_DYNAMIC 252option. 253This option must be in the kernel config file of the running kernel for this 254display to work. 255All devices are displayed as there is currently no way to filter them. 256The statistics displayed for the I/O latencies are the percentiles with 257sufficient data during the polling interval to compute. 258If a value cannot be estimated ``-'' is displayed. 259The P50 (also known as the median), P90, P99 and P99.9 values are computed if 260more than 2, 10, 100 or 1000 operations occurred during the polling interval. 261The latency is the hardware latency values, and does not include any software 262queuing time. 263The latencies are estimated based on histogram data computed by the CAM I/O 264scheduler and represent estimates of the actual value that are only good to 265two or three significant digits. 266The display of latency changes based on the scale of the latency to reflect 267the precision of the estimates and to fit on the available screen space. 268All latencies are reported in milliseconds. 269When color is enabled 270.Bl -bullet 271.It 272Values below the medium latency threshold are displayed in green. 273.It 274Values between the minimum latency and high latency thresholds are displayed 275in magenta. 276.It 277Values above the high latency thresholds are displayed in red. 278.Pp 279When color is disabled, the default foreground and background colors are always 280used. 281.Pp 282The following commands are specific to the 283.Ic iolat 284display; the minimum unambiguous prefix may be supplied. 285.Pp 286.Bl -tag -width Fl -compact 287.It Cm color 288Toggle the use of color in the display. 289The default is on. 290.It Cm hi=XXX 291Set the high latency threshold to XXX milliseconds. 292.It Cm med=XXX 293Set the medium latency threshold to XXX milliseconds. 294.It Cm read 295Toggle the display of statistics about read operations. 296The default is on. 297.It Cm write 298Toggle the display of statistics about write operations. 299The default is on. 300.It Cm trim 301Toggle the display of statistics about trim operations. 302The default is on. 303.El 304.El 305.It Ic iostat 306Display, in the lower window, statistics about processor use 307and disk throughput. 308Statistics on processor use appear as 309bar graphs of the amount of time executing in user mode (``user''), 310in user mode running low priority processes (``nice''), in 311system mode (``system''), in interrupt mode (``interrupt''), 312and idle (``idle''). 313Statistics 314on disk throughput show, for each drive, megabytes per second, 315average number of disk transactions per second, and 316average kilobytes of data per transaction. 317This information may be 318displayed as bar graphs or as rows of numbers which scroll downward. 319Bar 320graphs are shown by default. 321.Pp 322The following commands are specific to the 323.Ic iostat 324display; the minimum unambiguous prefix may be supplied. 325.Pp 326.Bl -tag -width Fl -compact 327.It Cm numbers 328Show the disk I/O statistics in numeric form. 329Values are 330displayed in numeric columns which scroll downward. 331.It Cm bars 332Show the disk I/O statistics in bar graph form (default). 333.It Cm kbpt 334Toggle the display of kilobytes per transaction. 335(the default is to 336not display kilobytes per transaction). 337.El 338.It Ic swap 339Show information about swap space usage on all the 340swap areas compiled into the kernel and processes that are swapped out 341as well as a summary of disk activity. 342.Pp 343The swap areas are displayed first with their name, sizes and 344usage percentage. 345The 346.Ar Used 347column indicates the total blocks used so far; 348the graph shows the percentage of space in use on each partition. 349If there are more than one swap partition in use, 350a total line is also shown. 351Areas known to the kernel, but not in use are shown as not available. 352.Pp 353Below the swap space statistics, 354processes are listed in order of higher swap area usage. 355Pid, username, a part of command line, the total use of swap space 356in bytes, the size of process, as well as per-process swap usage percentage and 357per-system swap space percentage are shown per process. 358.Pp 359At the bottom left is the disk usage display. 360It reports the number of 361kilobytes per transaction, transactions per second, megabytes 362per second and the percentage of the time the disk was busy averaged 363over the refresh period of the display (by default, five seconds). 364The system keeps statistics on most every storage device. 365In general, up 366to seven devices are displayed. 367The devices displayed by default are the 368first devices in the kernel's device list. 369See 370.Xr devstat 3 371and 372.Xr devstat 9 373for details on the devstat system. 374.It Ic vmstat 375Take over the entire display and show a (rather crowded) compendium 376of statistics related to virtual memory usage, process scheduling, 377device interrupts, system name translation caching, disk I/O etc. 378.Pp 379The upper left quadrant of the screen shows the number 380of users logged in and the load average over the last one, five, 381and fifteen minute intervals. 382Below this line are statistics on memory utilization. 383The first row of the table reports memory usage only among 384active processes, that is processes that have run in the previous 385twenty seconds. 386The second row reports on memory usage of all processes. 387The first column reports on the number of kilobytes in physical pages 388claimed by processes. 389The second column reports the number of kilobytes in physical pages that 390are devoted to read only text pages. 391The third and fourth columns report the same two figures for 392virtual pages, that is the number of kilobytes in pages that would be 393needed if all processes had all of their pages. 394Finally the last column shows the number of kilobytes in physical pages 395on the free list. 396.Pp 397Below the memory display is a list of the 398average number of threads (over the last refresh interval) 399that are runnable (`r'), in page wait (`p'), 400in disk wait other than paging (`d'), 401sleeping (`s'), and swapped out but desiring to run (`w'). 402The row also shows the average number of context switches 403(`Csw'), traps (`Trp'; includes page faults), system calls (`Sys'), 404interrupts (`Int'), network software interrupts (`Sof'), and page 405faults (`Flt'). 406.Pp 407Below the process queue length listing is a numerical listing and 408a bar graph showing the amount of 409system (shown as `='), interrupt (shown as `+'), user (shown as `>'), 410nice (shown as `-'), and idle time (shown as ` '). 411.Pp 412Below the process display are statistics on name translations. 413It lists the number of names translated in the previous interval, 414the number and percentage of the translations that were 415handled by the system wide name translation cache, and 416the number and percentage of the translations that were 417handled by the per process name translation cache. 418.Pp 419To the right of the name translations display are lines showing 420the number of dirty buffers in the buffer cache (`dtbuf'), 421desired maximum size of vnode cache (`desvn'), 422number of vnodes actually allocated (`numvn'), 423and 424number of allocated vnodes that are free (`frevn'). 425.Pp 426At the bottom left is the disk usage display. 427It reports the number of 428kilobytes per transaction, transactions per second, megabytes 429per second and the percentage of the time the disk was busy averaged 430over the refresh period of the display (by default, five seconds). 431The system keeps statistics on most every storage device. 432In general, up 433to seven devices are displayed. 434The devices displayed by default are the 435first devices in the kernel's device list. 436See 437.Xr devstat 3 438and 439.Xr devstat 9 440for details on the devstat system. 441.Pp 442Under the date in the upper right hand quadrant are statistics 443on paging and swapping activity. 444The first two columns report the average number of pages 445brought in and out per second over the last refresh interval 446due to page faults and the paging daemon. 447The third and fourth columns report the average number of pages 448brought in and out per second over the last refresh interval 449due to swap requests initiated by the scheduler. 450The first row of the display shows the average 451number of disk transfers per second over the last refresh interval; 452the second row of the display shows the average 453number of pages transferred per second over the last refresh interval. 454.Pp 455Below the paging statistics is a column of lines regarding the virtual 456memory system. 457The first few lines describe, 458in units (except as noted below) 459of pages per second averaged over the sampling interval, 460pages copied on write (`cow'), 461pages zero filled on demand (`zfod'), 462pages optimally zero filled on demand (`ozfod'), 463the ratio of the (average) ozfod / zfod as a percentage (`%ozfod'), 464pages freed by the page daemon (`daefr'), 465pages freed by exiting processes (`prcfr'), 466total pages freed (`totfr'), 467pages reactivated from the free list (`react'), 468the average number of 469times per second that the page daemon was awakened (`pdwak'), 470pages analyzed by the page daemon (`pdpgs'), 471and 472in-transit blocking page faults (`intrn'). 473Note that the units are special for `%ozfod' and `pdwak'. 474The next few lines describe, 475as amounts of memory in kilobytes, 476pages wired down (`wire'), 477active pages (`act'), 478inactive pages (`inact'), 479dirty pages queued for laundering (`laund'), 480and 481free pages (`free'). 482Note that the values displayed are the current transient ones; 483they are not averages. 484.Pp 485At the bottom of this column is a line showing the 486amount of virtual memory, in kilobytes, mapped into the buffer cache (`buf'). 487This statistic is not useful. 488It exists only as a placeholder for the corresponding useful statistic 489(the amount of real memory used to cache disks). 490The most important component of the latter (the amount of real memory 491used by the vm system to cache disks) is not available, 492but can be guessed from the `inact' amount under some system loads. 493.Pp 494Running down the right hand side of the display is a breakdown 495of the interrupts being handled by the system. 496At the top of the list is the total interrupts per second 497over the time interval. 498The rest of the column breaks down the total on a device 499by device basis. 500Only devices that have interrupted at least once since boot time are shown. 501.Pp 502The following commands are specific to the 503.Ic vmstat 504display; the minimum unambiguous prefix may be supplied. 505.Pp 506.Bl -tag -width Ar -compact 507.It Cm boot 508Display cumulative statistics since the system was booted. 509.It Cm run 510Display statistics as a running total from the point this 511command is given. 512.It Cm time 513Display statistics averaged over the refresh interval (the default). 514.It Cm zero 515Reset running statistics to zero. 516.El 517.It Ic zarc 518display arc cache usage and hit/miss statistics. 519.It Ic netstat 520Display, in the lower window, network connections. 521By default, 522network servers awaiting requests are not displayed. 523Each address 524is displayed in the format ``host.port'', with each shown symbolically, 525when possible. 526It is possible to have addresses displayed numerically, 527limit the display to a set of ports, hosts, and/or protocols 528(the minimum unambiguous prefix may be supplied): 529.Pp 530.Bl -tag -width Ar -compact 531.It Cm all 532Toggle the displaying of server processes awaiting requests (this 533is the equivalent of the 534.Fl a 535flag to 536.Xr netstat 1 ) . 537.It Cm numbers 538Display network addresses numerically. 539.It Cm names 540Display network addresses symbolically. 541.It Cm proto Ar protocol 542Display only network connections using the indicated 543.Ar protocol . 544Supported protocols are ``tcp'', ``udp'', and ``all''. 545.It Cm ignore Op Ar items 546Do not display information about connections associated with 547the specified hosts or ports. 548Hosts and ports may be specified 549by name (``vangogh'', ``ftp''), or numerically. 550Host addresses 551use the Internet dot notation (``128.32.0.9''). 552Multiple items 553may be specified with a single command by separating them with 554spaces. 555.It Cm display Op Ar items 556Display information about the connections associated with the 557specified hosts or ports. 558As for 559.Ar ignore , 560.Op Ar items 561may be names or numbers. 562.It Cm show Op Ar ports\&|hosts 563Show, on the command line, the currently selected protocols, 564hosts, and ports. 565Hosts and ports which are being ignored 566are prefixed with a `!'. 567If 568.Ar ports 569or 570.Ar hosts 571is supplied as an argument to 572.Cm show , 573then only the requested information will be displayed. 574.It Cm reset 575Reset the port, host, and protocol matching mechanisms to the default 576(any protocol, port, or host). 577.El 578.It Ic ifstat 579Display the network traffic going through active interfaces on the 580system. 581Idle interfaces will not be displayed until they receive some 582traffic. 583.Pp 584For each interface being displayed, the current, peak and total 585statistics are displayed for incoming and outgoing traffic. 586By default, 587the 588.Ic ifstat 589display will automatically scale the units being used so that they are 590in a human-readable format. 591The scaling units used for the current and 592peak 593traffic columns can be altered by the 594.Ic scale 595command. 596.Bl -tag -width ".Cm scale Op Ar units" 597.It Cm scale Op Ar units 598Modify the scale used to display the current and peak traffic over all 599interfaces. 600The following units are recognised: kbit, kbyte, mbit, 601mbyte, gbit, gbyte and auto. 602.It Cm pps 603Show statistics in packets per second instead of bytes/bits per second. 604A subsequent call of 605.Ic pps 606switches this mode off. 607.It Cm match Op Ar patterns 608Display only interfaces that match pattern provided as an argument. 609Patterns should be in shell syntax separated by whitespaces or commas. 610If this command is called without arguments then all interfaces are displayed. 611For example: 612.Pp 613.Dl match em0, bge1 614.Pp 615This will display em0 and bge1 interfaces. 616.Pp 617.Dl match em*, bge*, lo0 618.Pp 619This will display all 620.Ic em 621interfaces, all 622.Ic bge 623interfaces and the loopback interface. 624.El 625.El 626.Pp 627Commands to switch between displays may be abbreviated to the 628minimum unambiguous prefix; for example, ``io'' for ``iostat''. 629Certain information may be discarded when the screen size is 630insufficient for display. 631For example, on a machine with 10 632drives the 633.Ic iostat 634bar graph displays only 3 drives on a 24 line terminal. 635When 636a bar graph would overflow the allotted screen space it is 637truncated and the actual value is printed ``over top'' of the bar. 638.Pp 639The following commands are common to each display which shows 640information about disk drives. 641These commands are used to 642select a set of drives to report on, should your system have 643more drives configured than can normally be displayed on the 644screen. 645.Pp 646.Bl -tag -width Ar -compact 647.It Cm ignore Op Ar drives 648Do not display information about the drives indicated. 649Multiple 650drives may be specified, separated by spaces. 651.It Cm display Op Ar drives 652Display information about the drives indicated. 653Multiple drives 654may be specified, separated by spaces. 655.It Cm only Op Ar drives 656Display only the specified drives. 657Multiple drives may be specified, 658separated by spaces. 659.It Cm drives 660Display a list of available devices. 661.It Cm match Xo 662.Ar type , Ns Ar if , Ns Ar pass 663.Op | Ar ... 664.Xc 665Display devices matching the given pattern. 666The basic matching 667expressions are the same as those used in 668.Xr iostat 8 669with one difference. 670Instead of specifying multiple 671.Fl t 672arguments which are then ORed together, the user instead specifies multiple 673matching expressions joined by the pipe 674.Pq Ql \&| 675character. 676The comma 677separated arguments within each matching expression are ANDed together, and 678then the pipe separated matching expressions are ORed together. 679Any 680device matching the combined expression will be displayed, if there is room 681to display it. 682For example: 683.Pp 684.Dl match da,scsi | cd,ide 685.Pp 686This will display all SCSI Direct Access devices and all IDE CDROM devices. 687.Pp 688.Dl match da | sa | cd,pass 689.Pp 690This will display all Direct Access devices, all Sequential Access devices, 691and all passthrough devices that provide access to CDROM drives. 692.El 693.Sh FILES 694.Bl -tag -width /boot/kernel/kernel -compact 695.It Pa /boot/kernel/kernel 696For the namelist. 697.It Pa /dev/kmem 698For information in main memory. 699.It Pa /etc/hosts 700For host names. 701.It Pa /etc/networks 702For network names. 703.It Pa /etc/services 704For port names. 705.El 706.Sh SEE ALSO 707.Xr netstat 1 , 708.Xr kvm 3 , 709.Xr icmp 4 , 710.Xr icmp6 4 , 711.Xr ip 4 , 712.Xr ip6 4 , 713.Xr tcp 4 , 714.Xr udp 4 , 715.Xr gstat 8 , 716.Xr iostat 8 , 717.Xr vmstat 8 718.Sh HISTORY 719The 720.Nm 721program appeared in 722.Bx 4.3 . 723The 724.Ic icmp , 725.Ic ip , 726and 727.Ic tcp 728displays appeared in 729.Fx 3.0 ; 730the notion of having different display modes for the 731ICMP, IP, TCP, and UDP statistics was stolen from the 732.Fl C 733option to 734.Xr netstat 1 735in Silicon Graphics' IRIX system. 736.Sh BUGS 737Certain displays presume a minimum of 80 characters per line. 738Ifstat does not detect new interfaces. 739The 740.Ic vmstat 741display looks out of place because it is (it was added in as 742a separate display rather than created as a new program). 743The 744.Ic iolat 745command does not implement the common device commands including 746filtering, as it does not use the 747.Xr devstat 3 748mechanism to obtain its statistics. 749