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