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 February 10, 2021 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 262queueing 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 Values below the medium latency threshold are displayed in green. 272.It Values between the minimum latency and high latency thresholds are displayed 273in magenta. 274.It Values 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.It Ic iostat 302Display, in the lower window, statistics about processor use 303and disk throughput. 304Statistics on processor use appear as 305bar graphs of the amount of time executing in user mode (``user''), 306in user mode running low priority processes (``nice''), in 307system mode (``system''), in interrupt mode (``interrupt''), 308and idle (``idle''). 309Statistics 310on disk throughput show, for each drive, megabytes per second, 311average number of disk transactions per second, and 312average kilobytes of data per transaction. 313This information may be 314displayed as bar graphs or as rows of numbers which scroll downward. 315Bar 316graphs are shown by default. 317.Pp 318The following commands are specific to the 319.Ic iostat 320display; the minimum unambiguous prefix may be supplied. 321.Pp 322.Bl -tag -width Fl -compact 323.It Cm numbers 324Show the disk I/O statistics in numeric form. 325Values are 326displayed in numeric columns which scroll downward. 327.It Cm bars 328Show the disk I/O statistics in bar graph form (default). 329.It Cm kbpt 330Toggle the display of kilobytes per transaction. 331(the default is to 332not display kilobytes per transaction). 333.El 334.It Ic swap 335Show information about swap space usage on all the 336swap areas compiled into the kernel and processes that are swapped out 337as well as a summary of disk activity. 338.Pp 339The swap areas are displayed first with their name, sizes and 340usage percentage. 341The 342.Ar Used 343column indicates the total blocks used so far; 344the graph shows the percentage of space in use on each partition. 345If there are more than one swap partition in use, 346a total line is also shown. 347Areas known to the kernel, but not in use are shown as not available. 348.Pp 349Below the swap space statistics, 350processes are listed in order of higher swap area usage. 351Pid, username, a part of command line, the total use of swap space 352in bytes, the size of process, as well as per-process swap usage percentage and 353per-system swap space percentage are shown per process. 354.Pp 355At the bottom left is the disk usage display. 356It reports the number of 357kilobytes per transaction, transactions per second, megabytes 358per second and the percentage of the time the disk was busy averaged 359over the refresh period of the display (by default, five seconds). 360The system keeps statistics on most every storage device. 361In general, up 362to seven devices are displayed. 363The devices displayed by default are the 364first devices in the kernel's device list. 365See 366.Xr devstat 3 367and 368.Xr devstat 9 369for details on the devstat system. 370.It Ic vmstat 371Take over the entire display and show a (rather crowded) compendium 372of statistics related to virtual memory usage, process scheduling, 373device interrupts, system name translation caching, disk I/O etc. 374.Pp 375The upper left quadrant of the screen shows the number 376of users logged in and the load average over the last one, five, 377and fifteen minute intervals. 378Below this line are statistics on memory utilization. 379The first row of the table reports memory usage only among 380active processes, that is processes that have run in the previous 381twenty seconds. 382The second row reports on memory usage of all processes. 383The first column reports on the number of kilobytes in physical pages 384claimed by processes. 385The second column reports the number of kilobytes in physical pages that 386are devoted to read only text pages. 387The third and fourth columns report the same two figures for 388virtual pages, that is the number of kilobytes in pages that would be 389needed if all processes had all of their pages. 390Finally the last column shows the number of kilobytes in physical pages 391on the free list. 392.Pp 393Below the memory display is a list of the 394average number of threads (over the last refresh interval) 395that are runnable (`r'), in page wait (`p'), 396in disk wait other than paging (`d'), 397sleeping (`s'), and swapped out but desiring to run (`w'). 398The row also shows the average number of context switches 399(`Csw'), traps (`Trp'; includes page faults), system calls (`Sys'), 400interrupts (`Int'), network software interrupts (`Sof'), and page 401faults (`Flt'). 402.Pp 403Below the process queue length listing is a numerical listing and 404a bar graph showing the amount of 405system (shown as `='), interrupt (shown as `+'), user (shown as `>'), 406nice (shown as `-'), and idle time (shown as ` '). 407.Pp 408Below the process display are statistics on name translations. 409It lists the number of names translated in the previous interval, 410the number and percentage of the translations that were 411handled by the system wide name translation cache, and 412the number and percentage of the translations that were 413handled by the per process name translation cache. 414.Pp 415To the right of the name translations display are lines showing 416the number of dirty buffers in the buffer cache (`dtbuf'), 417desired maximum size of vnode cache (`desvn'), 418number of vnodes actually allocated (`numvn'), 419and 420number of allocated vnodes that are free (`frevn'). 421.Pp 422At the bottom left is the disk usage display. 423It reports the number of 424kilobytes per transaction, transactions per second, megabytes 425per second and the percentage of the time the disk was busy averaged 426over the refresh period of the display (by default, five seconds). 427The system keeps statistics on most every storage device. 428In general, up 429to seven devices are displayed. 430The devices displayed by default are the 431first devices in the kernel's device list. 432See 433.Xr devstat 3 434and 435.Xr devstat 9 436for details on the devstat system. 437.Pp 438Under the date in the upper right hand quadrant are statistics 439on paging and swapping activity. 440The first two columns report the average number of pages 441brought in and out per second over the last refresh interval 442due to page faults and the paging daemon. 443The third and fourth columns report the average number of pages 444brought in and out per second over the last refresh interval 445due to swap requests initiated by the scheduler. 446The first row of the display shows the average 447number of disk transfers per second over the last refresh interval; 448the second row of the display shows the average 449number of pages transferred per second over the last refresh interval. 450.Pp 451Below the paging statistics is a column of lines regarding the virtual 452memory system. 453The first few lines describe, 454in units (except as noted below) 455of pages per second averaged over the sampling interval, 456pages copied on write (`cow'), 457pages zero filled on demand (`zfod'), 458pages optimally zero filled on demand (`ozfod'), 459the ratio of the (average) ozfod / zfod as a percentage (`%ozfod'), 460pages freed by the page daemon (`daefr'), 461pages freed by exiting processes (`prcfr'), 462total pages freed (`totfr'), 463pages reactivated from the free list (`react'), 464the average number of 465times per second that the page daemon was awakened (`pdwak'), 466pages analyzed by the page daemon (`pdpgs'), 467and 468in-transit blocking page faults (`intrn'). 469Note that the units are special for `%ozfod' and `pdwak'. 470The next few lines describe, 471as amounts of memory in kilobytes, 472pages wired down (`wire'), 473active pages (`act'), 474inactive pages (`inact'), 475dirty pages queued for laundering (`laund'), 476and 477free pages (`free'). 478Note that the values displayed are the current transient ones; 479they are not averages. 480.Pp 481At the bottom of this column is a line showing the 482amount of virtual memory, in kilobytes, mapped into the buffer cache (`buf'). 483This statistic is not useful. 484It exists only as a placeholder for the corresponding useful statistic 485(the amount of real memory used to cache disks). 486The most important component of the latter (the amount of real memory 487used by the vm system to cache disks) is not available, 488but can be guessed from the `inact' amount under some system loads. 489.Pp 490Running down the right hand side of the display is a breakdown 491of the interrupts being handled by the system. 492At the top of the list is the total interrupts per second 493over the time interval. 494The rest of the column breaks down the total on a device 495by device basis. 496Only devices that have interrupted at least once since boot time are shown. 497.Pp 498The following commands are specific to the 499.Ic vmstat 500display; the minimum unambiguous prefix may be supplied. 501.Pp 502.Bl -tag -width Ar -compact 503.It Cm boot 504Display cumulative statistics since the system was booted. 505.It Cm run 506Display statistics as a running total from the point this 507command is given. 508.It Cm time 509Display statistics averaged over the refresh interval (the default). 510.It Cm zero 511Reset running statistics to zero. 512.El 513.It Ic zarc 514display arc cache usage and hit/miss statistics. 515.It Ic netstat 516Display, in the lower window, network connections. 517By default, 518network servers awaiting requests are not displayed. 519Each address 520is displayed in the format ``host.port'', with each shown symbolically, 521when possible. 522It is possible to have addresses displayed numerically, 523limit the display to a set of ports, hosts, and/or protocols 524(the minimum unambiguous prefix may be supplied): 525.Pp 526.Bl -tag -width Ar -compact 527.It Cm all 528Toggle the displaying of server processes awaiting requests (this 529is the equivalent of the 530.Fl a 531flag to 532.Xr netstat 1 ) . 533.It Cm numbers 534Display network addresses numerically. 535.It Cm names 536Display network addresses symbolically. 537.It Cm proto Ar protocol 538Display only network connections using the indicated 539.Ar protocol . 540Supported protocols are ``tcp'', ``udp'', and ``all''. 541.It Cm ignore Op Ar items 542Do not display information about connections associated with 543the specified hosts or ports. 544Hosts and ports may be specified 545by name (``vangogh'', ``ftp''), or numerically. 546Host addresses 547use the Internet dot notation (``128.32.0.9''). 548Multiple items 549may be specified with a single command by separating them with 550spaces. 551.It Cm display Op Ar items 552Display information about the connections associated with the 553specified hosts or ports. 554As for 555.Ar ignore , 556.Op Ar items 557may be names or numbers. 558.It Cm show Op Ar ports\&|hosts 559Show, on the command line, the currently selected protocols, 560hosts, and ports. 561Hosts and ports which are being ignored 562are prefixed with a `!'. 563If 564.Ar ports 565or 566.Ar hosts 567is supplied as an argument to 568.Cm show , 569then only the requested information will be displayed. 570.It Cm reset 571Reset the port, host, and protocol matching mechanisms to the default 572(any protocol, port, or host). 573.El 574.It Ic ifstat 575Display the network traffic going through active interfaces on the 576system. 577Idle interfaces will not be displayed until they receive some 578traffic. 579.Pp 580For each interface being displayed, the current, peak and total 581statistics are displayed for incoming and outgoing traffic. 582By default, 583the 584.Ic ifstat 585display will automatically scale the units being used so that they are 586in a human-readable format. 587The scaling units used for the current and 588peak 589traffic columns can be altered by the 590.Ic scale 591command. 592.Bl -tag -width ".Cm scale Op Ar units" 593.It Cm scale Op Ar units 594Modify the scale used to display the current and peak traffic over all 595interfaces. 596The following units are recognised: kbit, kbyte, mbit, 597mbyte, gbit, gbyte and auto. 598.It Cm pps 599Show statistics in packets per second instead of bytes/bits per second. 600A subsequent call of 601.Ic pps 602switches this mode off. 603.It Cm match Op Ar patterns 604Display only interfaces that match pattern provided as an argument. 605Patterns should be in shell syntax separated by whitespaces or commas. 606If this command is called without arguments then all interfaces are displayed. 607For example: 608.Pp 609.Dl match em0, bge1 610.Pp 611This will display em0 and bge1 interfaces. 612.Pp 613.Dl match em*, bge*, lo0 614.Pp 615This will display all 616.Ic em 617interfaces, all 618.Ic bge 619interfaces and the loopback interface. 620.El 621.El 622.Pp 623Commands to switch between displays may be abbreviated to the 624minimum unambiguous prefix; for example, ``io'' for ``iostat''. 625Certain information may be discarded when the screen size is 626insufficient for display. 627For example, on a machine with 10 628drives the 629.Ic iostat 630bar graph displays only 3 drives on a 24 line terminal. 631When 632a bar graph would overflow the allotted screen space it is 633truncated and the actual value is printed ``over top'' of the bar. 634.Pp 635The following commands are common to each display which shows 636information about disk drives. 637These commands are used to 638select a set of drives to report on, should your system have 639more drives configured than can normally be displayed on the 640screen. 641.Pp 642.Bl -tag -width Ar -compact 643.It Cm ignore Op Ar drives 644Do not display information about the drives indicated. 645Multiple 646drives may be specified, separated by spaces. 647.It Cm display Op Ar drives 648Display information about the drives indicated. 649Multiple drives 650may be specified, separated by spaces. 651.It Cm only Op Ar drives 652Display only the specified drives. 653Multiple drives may be specified, 654separated by spaces. 655.It Cm drives 656Display a list of available devices. 657.It Cm match Xo 658.Ar type , Ns Ar if , Ns Ar pass 659.Op | Ar ... 660.Xc 661Display devices matching the given pattern. 662The basic matching 663expressions are the same as those used in 664.Xr iostat 8 665with one difference. 666Instead of specifying multiple 667.Fl t 668arguments which are then ORed together, the user instead specifies multiple 669matching expressions joined by the pipe 670.Pq Ql \&| 671character. 672The comma 673separated arguments within each matching expression are ANDed together, and 674then the pipe separated matching expressions are ORed together. 675Any 676device matching the combined expression will be displayed, if there is room 677to display it. 678For example: 679.Pp 680.Dl match da,scsi | cd,ide 681.Pp 682This will display all SCSI Direct Access devices and all IDE CDROM devices. 683.Pp 684.Dl match da | sa | cd,pass 685.Pp 686This will display all Direct Access devices, all Sequential Access devices, 687and all passthrough devices that provide access to CDROM drives. 688.El 689.Sh FILES 690.Bl -tag -width /boot/kernel/kernel -compact 691.It Pa /boot/kernel/kernel 692For the namelist. 693.It Pa /dev/kmem 694For information in main memory. 695.It Pa /etc/hosts 696For host names. 697.It Pa /etc/networks 698For network names. 699.It Pa /etc/services 700For port names. 701.El 702.Sh SEE ALSO 703.Xr netstat 1 , 704.Xr kvm 3 , 705.Xr icmp 4 , 706.Xr icmp6 4 , 707.Xr ip 4 , 708.Xr ip6 4 , 709.Xr tcp 4 , 710.Xr udp 4 , 711.Xr gstat 8 , 712.Xr iostat 8 , 713.Xr vmstat 8 714.Sh HISTORY 715The 716.Nm 717program appeared in 718.Bx 4.3 . 719The 720.Ic icmp , 721.Ic ip , 722and 723.Ic tcp 724displays appeared in 725.Fx 3.0 ; 726the notion of having different display modes for the 727ICMP, IP, TCP, and UDP statistics was stolen from the 728.Fl C 729option to 730.Xr netstat 1 731in Silicon Graphics' IRIX system. 732.Sh BUGS 733Certain displays presume a minimum of 80 characters per line. 734Ifstat does not detect new interfaces. 735The 736.Ic vmstat 737display looks out of place because it is (it was added in as 738a separate display rather than created as a new program). 739The 740.Ic iolat 741command doesn't implement the common device commands including 742filtering, as it doesn't use the 743.Xr devstat 3 744mechanism to obtain its statistics. 745