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