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.\" 34.Dd September 9, 1997 35.Dt SYSTAT 1 36.Os BSD 4.3 37.Sh NAME 38.Nm systat 39.Nd display system statistics on a crt 40.Sh SYNOPSIS 41.Nm 42.Op Fl display 43.Op Ar refresh-interval 44.Sh DESCRIPTION 45.Nm Systat 46displays various system statistics in a screen oriented fashion 47using the curses screen display library, 48.Xr curses 3 . 49.Pp 50While 51.Nm 52is running the screen is usually divided into two windows (an exception 53is the vmstat display which uses the entire screen). The 54upper window depicts the current system load average. The 55information displayed in the lower window may vary, depending on 56user commands. The last line on the screen is reserved for user 57input and error messages. 58.Pp 59By default 60.Nm 61displays the processes getting the largest percentage of the processor 62in the lower window. Other displays show swap space usage, disk 63.Tn I/O 64statistics (a la 65.Xr iostat 8 ) , 66virtual memory statistics (a la 67.Xr vmstat 8 ) , 68network ``mbuf'' utilization, 69.Tn TCP/IP 70statistics, 71and network connections (a la 72.Xr netstat 1 ) . 73.Pp 74Input is interpreted at two different levels. 75A ``global'' command interpreter processes all keyboard input. 76If this command interpreter fails to recognize a command, the 77input line is passed to a per-display command interpreter. This 78allows each display to have certain display-specific commands. 79.Pp 80Command line options: 81.Bl -tag -width "refresh_interval" 82.It Fl Ns Ar display 83The 84.Fl 85flag expects 86.Ar display 87to be one of: 88.Ic icmp , 89.Ic iostat , 90.Ic ip , 91.Ic mbufs , 92.Ic netstat , 93.Ic pigs , 94.Ic swap , 95.Ic tcp , 96or 97.Ic vmstat . 98These displays can also be requested interactively (without the 99.Dq Fl ) 100and are described in 101full detail below. 102.It Ar refresh-interval 103The 104.Ar refresh-value 105specifies the screen refresh time interval in seconds. 106.El 107.Pp 108Certain characters cause immediate action by 109.Nm systat . 110These are 111.Bl -tag -width Fl 112.It Ic \&^L 113Refresh the screen. 114.It Ic \&^G 115Print the name of the current ``display'' being shown in 116the lower window and the refresh interval. 117.It Ic \&^Z 118Stop 119.Nm systat . 120.It Ic \&: 121Move the cursor to the command line and interpret the input 122line typed as a command. While entering a command the 123current character erase, word erase, and line kill characters 124may be used. 125.El 126.Pp 127The following commands are interpreted by the ``global'' 128command interpreter. 129.Bl -tag -width Fl 130.It Ic help 131Print the names of the available displays on the command line. 132.It Ic load 133Print the load average over the past 1, 5, and 15 minutes 134on the command line. 135.It Ic stop 136Stop refreshing the screen. 137.It Xo 138.Op Ic start 139.Op Ar number 140.Xc 141Start (continue) refreshing the screen. If a second, numeric, 142argument is provided it is interpreted as a refresh interval 143(in seconds). 144Supplying only a number will set the refresh interval to this 145value. 146.It Ic quit 147Exit 148.Nm systat . 149(This may be abbreviated to 150.Ic q . ) 151.El 152.Pp 153The available displays are: 154.Bl -tag -width Ic 155.It Ic pigs 156Display, in the lower window, those processes resident in main 157memory and getting the 158largest portion of the processor (the default display). 159When less than 100% of the 160processor is scheduled to user processes, the remaining time 161is accounted to the ``idle'' process. 162.It Ic icmp 163Display, in the lower window, statistics about messages received and 164transmitted by the Internet Control Message Protocol 165.Pq Dq Tn ICMP . 166The left half of the screen displays information about received 167packets, and the right half displays information regarding transmitted 168packets. 169.Pp 170The 171.Ic icmp 172display understands two commands: 173.Ic mode 174and 175.Ic reset . 176The 177.Ic mode 178command is used to select one of four display modes, given as its argument: 179.Bl -tag -width absoluteXX -compact 180.It Ic rate : 181show the rate of change of each value in packets (the default) 182per second 183.It Ic delta : 184show the rate of change of each value in packets per refresh interval 185.It Ic since : 186show the total change of each value since the display was last reset 187.It Ic absolute : 188show the absolute value of each statistic 189.El 190.Pp 191The 192.Ic reset 193command resets the baseline for 194.Ic since 195mode. The 196.Ic mode 197command with no argument will display the current mode in the command 198line. 199.It Ic ip 200Otherwise identical to the 201.Ic icmp 202display, except that it displays 203.Tn IP 204and 205.Tn UDP 206statistics. 207.It Ic tcp 208Like 209.Ic icmp , 210but with 211.Tn TCP 212statistics. 213.It Ic iostat 214Display, in the lower window, statistics about processor use 215and disk throughput. Statistics on processor use appear as 216bar graphs of the amount of time executing in user mode (``user''), 217in user mode running low priority processes (``nice''), in 218system mode (``system''), in interrupt mode (``interrupt''), 219and idle (``idle''). Statistics 220on disk throughput show, for each drive, megabytes per second, 221average number of disk transactions per second, and 222average kilobytes of data per transaction. This information may be 223displayed as bar graphs or as rows of numbers which scroll downward. Bar 224graphs are shown by default. 225.Pp 226The following commands are specific to the 227.Ic iostat 228display; the minimum unambiguous prefix may be supplied. 229.Pp 230.Bl -tag -width Fl -compact 231.It Cm numbers 232Show the disk 233.Tn I/O 234statistics in numeric form. Values are 235displayed in numeric columns which scroll downward. 236.It Cm bars 237Show the disk 238.Tn I/O 239statistics in bar graph form (default). 240.It Cm kbpt 241Toggle the display of kilobytes per transaction. (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 seeks, transfers, and number 308of kilobyte blocks transferred per second averaged over the 309refresh period of the display (by default, five seconds). 310For some disks it also reports the average milliseconds per seek. 311Note that the system only keeps statistics on at most eight disks 312(this is controlled by the constant 313.Dv DK_NDRIVE 314in 315.Aq Pa sys/dkstat.h 316as a kernel compile-time constant). 317.Pp 318Under the date in the upper right hand quadrant are statistics 319on paging and swapping activity. 320The first two columns report the average number of pages 321brought in and out per second over the last refresh interval 322due to page faults and the paging daemon. 323The third and fourth columns report the average number of pages 324brought in and out per second over the last refresh interval 325due to swap requests initiated by the scheduler. 326The first row of the display shows the average 327number of disk transfers per second over the last refresh interval; 328the second row of the display shows the average 329number of pages transferred per second over the last refresh interval. 330.Pp 331Below the paging statistics is a column of lines regarding the virtual 332memory system which list the average number of 333pages copied on write (`cow'), 334pages zero filled on demand (`zfod'), 335pages wired down (`wire'), 336active pages (`act'), 337inactive pages (`inact'), 338pages on the buffer cache queue (`cache'), 339number of free pages (`free'), 340pages freed by the page daemon (`daefr'), 341pages freed by exiting processes (`prcfr'), 342pages reactivated from the free list (`react'), 343times the page daemon was awakened (`pdwak'), 344pages analyzed by the page daemon (`pdpgs'), 345and 346intransit blocking page faults (`intrn') 347per second over the refresh interval. 348.Pp 349At the bottom of this column are lines showing the 350amount of memory, in kilobytes, used for the buffer cache (`buf'), 351desired maximum size of vnode cache (`desiredvnodes') (mostly unused, 352except to size the name cache), 353number of vnodes actually allocated (`numvnodes'), 354and 355number of allocated vnodes that are free (`freevnodes'). 356.Pp 357Running down the right hand side of the display is a breakdown 358of the interrupts being handled by the system. 359At the top of the list is the total interrupts per second 360over the time interval. 361The rest of the column breaks down the total on a device 362by device basis. 363Only devices that have interrupted at least once since boot time are shown. 364.Pp 365The following commands are specific to the 366.Ic vmstat 367display; the minimum unambiguous prefix may be supplied. 368.Pp 369.Bl -tag -width Ar -compact 370.It Cm boot 371Display cumulative statistics since the system was booted. 372.It Cm run 373Display statistics as a running total from the point this 374command is given. 375.It Cm time 376Display statistics averaged over the refresh interval (the default). 377.It Cm zero 378Reset running statistics to zero. 379.El 380.It Ic netstat 381Display, in the lower window, network connections. By default, 382network servers awaiting requests are not displayed. Each address 383is displayed in the format ``host.port'', with each shown symbolically, 384when possible. It is possible to have addresses displayed numerically, 385limit the display to a set of ports, hosts, and/or protocols 386(the minimum unambiguous prefix may be supplied): 387.Pp 388.Bl -tag -width Ar -compact 389.It Cm all 390Toggle the displaying of server processes awaiting requests (this 391is the equivalent of the 392.Fl a 393flag to 394.Xr netstat 1 ) . 395.It Cm numbers 396Display network addresses numerically. 397.It Cm names 398Display network addresses symbolically. 399.It Cm proto Ar protocol 400Display only network connections using the indicated 401.Ar protocol . 402Supported protocols are ``tcp'', ``udp'', and ``all''. 403.It Cm ignore Op Ar items 404Do not display information about connections associated with 405the specified hosts or ports. Hosts and ports may be specified 406by name (``vangogh'', ``ftp''), or numerically. Host addresses 407use the Internet dot notation (``128.32.0.9''). Multiple items 408may be specified with a single command by separating them with 409spaces. 410.It Cm display Op Ar items 411Display information about the connections associated with the 412specified hosts or ports. As for 413.Ar ignore , 414.Op Ar items 415may be names or numbers. 416.It Cm show Op Ar ports\&|hosts 417Show, on the command line, the currently selected protocols, 418hosts, and ports. Hosts and ports which are being ignored 419are prefixed with a `!'. If 420.Ar ports 421or 422.Ar hosts 423is supplied as an argument to 424.Cm show , 425then only the requested information will be displayed. 426.It Cm reset 427Reset the port, host, and protocol matching mechanisms to the default 428(any protocol, port, or host). 429.El 430.El 431.Pp 432Commands to switch between displays may be abbreviated to the 433minimum unambiguous prefix; for example, ``io'' for ``iostat''. 434Certain information may be discarded when the screen size is 435insufficient for display. For example, on a machine with 10 436drives the 437.Ic iostat 438bar graph displays only 3 drives on a 24 line terminal. When 439a bar graph would overflow the allotted screen space it is 440truncated and the actual value is printed ``over top'' of the bar. 441.Pp 442The following commands are common to each display which shows 443information about disk drives. These commands are used to 444select a set of drives to report on, should your system have 445more drives configured than can normally be displayed on the 446screen. 447.Pp 448.Bl -tag -width Tx -compact 449.It Cm ignore Op Ar drives 450Do not display information about the drives indicated. Multiple 451drives may be specified, separated by spaces. 452.It Cm display Op Ar drives 453Display information about the drives indicated. Multiple drives 454may be specified, separated by spaces. 455.It Cm only Op Ar drives 456Display only the specified drives. Multiple drives may be specified, 457separated by spaces. 458.It Cm drives 459Display a list of available devices. 460.It Cm match Ar type,if,pass Op Ar | ... 461Display devivces matching the given pattern. The basic matching 462expressions are the same as those used in 463.Xr iostat 8 464with one difference. Instead of specifying multiple 465.Fl t 466arguments which are then ORed together, the user instead specifys multiple 467matching expressions joined by the pipe ( | ) character. The comma 468separated arguments within each matching expression are ANDed together, and 469then the pipe separated matching expressions are ORed together. Any 470device matching the combined expression will be displayed, if there is room 471to display it. For example: 472.Pp 473.Dl match da,scsi | cd,ide 474.Pp 475This will display all SCSI Direct Access devices and all IDE CDROM devices. 476.Pp 477.Dl match da | sa | cd,pass 478.Pp 479This will display all Direct Access devices, all Sequential Access devices, 480and all passthrough devices that provide access to CDROM drives. 481.El 482.Sh SEE ALSO 483.Xr iostat 1 , 484.Xr netstat 1 , 485.Xr vmstat 1 , 486.Xr icmp 4 , 487.Xr ip 4 , 488.Xr tcp 4 , 489.Xr udp 4 490.Sh FILES 491.Bl -tag -width /etc/networks -compact 492.It Pa /kernel 493For the namelist. 494.It Pa /dev/kmem 495For information in main memory. 496.It Pa /dev/drum 497For information about swapped out processes. 498.It Pa /etc/hosts 499For host names. 500.It Pa /etc/networks 501For network names. 502.It Pa /etc/services 503For port names. 504.El 505.Sh HISTORY 506The 507.Nm 508program appeared in 509.Bx 4.3 . 510The 511.Ic icmp , 512.Ic ip , 513and 514.Ic tcp 515displays appeared in 516.Fx 3.0 ; 517the notion of having different display modes for the 518.Tn ICMP , 519.Tn IP , 520.Tn TCP , 521and 522.Tn UDP 523statistics was stolen from the 524.Fl C 525option to 526.Xr netstat 1 527in Silicon Graphics' 528.Tn IRIX 529system. 530.Sh BUGS 531Takes 2-10 percent of the cpu. 532Certain displays presume a minimum of 80 characters per line. 533The 534.Ic vmstat 535display looks out of place because it is (it was added in as 536a separate display rather than created as a new program). 537