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