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