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