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