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