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