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