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