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 December 30, 1993 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 systat 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 systat 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 systat 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, and network connections (a la 69.Xr netstat 1 ) . 70.Pp 71Input is interpreted at two different levels. 72A ``global'' command interpreter processes all keyboard input. 73If this command interpreter fails to recognize a command, the 74input line is passed to a per-display command interpreter. This 75allows each display to have certain display-specific commands. 76.Pp 77Command line options: 78.Bl -tag -width "refresh_interval" 79.It Fl Ns Ar display 80The 81.Fl 82flag expects 83.Ar display 84to be one of: 85.Ic pigs , 86.Ic iostat , 87.Ic swap , 88.Ic mbufs , 89.Ic vmstat 90or 91.Ic netstat . 92These displays can also be requested interactively (without the 93.Dq Fl ) 94and are described in 95full detail below. 96.It Ar refresh-interval 97The 98.Ar refresh-value 99specifies the screen refresh time interval in seconds. 100.El 101.Pp 102Certain characters cause immediate action by 103.Nm systat . 104These are 105.Bl -tag -width Fl 106.It Ic \&^L 107Refresh the screen. 108.It Ic \&^G 109Print the name of the current ``display'' being shown in 110the lower window and the refresh interval. 111.It Ic \&^Z 112Stop 113.Nm systat . 114.It Ic \&: 115Move the cursor to the command line and interpret the input 116line typed as a command. While entering a command the 117current character erase, word erase, and line kill characters 118may be used. 119.El 120.Pp 121The following commands are interpreted by the ``global'' 122command interpreter. 123.Bl -tag -width Fl 124.It Ic help 125Print the names of the available displays on the command line. 126.It Ic load 127Print the load average over the past 1, 5, and 15 minutes 128on the command line. 129.It Ic stop 130Stop refreshing the screen. 131.It Xo 132.Op Ic start 133.Op Ar number 134.Xc 135Start (continue) refreshing the screen. If a second, numeric, 136argument is provided it is interpreted as a refresh interval 137(in seconds). 138Supplying only a number will set the refresh interval to this 139value. 140.It Ic quit 141Exit 142.Nm systat . 143(This may be abbreviated to 144.Ic q . ) 145.El 146.Pp 147The available displays are: 148.Bl -tag -width Ic 149.It Ic pigs 150Display, in the lower window, those processes resident in main 151memory and getting the 152largest portion of the processor (the default display). 153When less than 100% of the 154processor is scheduled to user processes, the remaining time 155is accounted to the ``idle'' process. 156.It Ic iostat 157Display, in the lower window, statistics about processor use 158and disk throughput. Statistics on processor use appear as 159bar graphs of the amount of time executing in user mode (``user''), 160in user mode running low priority processes (``nice''), in 161system mode (``system''), in interrupt mode (``interrupt''), 162and idle (``idle''). Statistics 163on disk throughput show, for each drive, kilobytes of data transferred, 164number of disk transactions performed, and average seek time 165(in milliseconds). This information may be displayed as 166bar graphs or as rows of numbers which scroll downward. Bar 167graphs are shown by default; 168.Pp 169The following commands are specific to the 170.Ic iostat 171display; the minimum unambiguous prefix may be supplied. 172.Pp 173.Bl -tag -width Fl -compact 174.It Cm numbers 175Show the disk 176.Tn I/O 177statistics in numeric form. Values are 178displayed in numeric columns which scroll downward. 179.It Cm bars 180Show the disk 181.Tn I/O 182statistics in bar graph form (default). 183.It Cm msps 184Toggle the display of average seek time (the default is to 185not display seek times). 186.El 187.It Ic swap 188Show information about swap space usage on all the 189swap areas compiled into the kernel. 190The first column is the device name of the partition. 191The next column is the total space available in the partition. 192The 193.Ar Used 194column indicates the total blocks used so far; 195the graph shows the percentage of space in use on each partition. 196If there are more than one swap partition in use, 197a total line is also shown. 198Areas known to the kernel, but not in use are shown as not available. 199.It Ic mbufs 200Display, in the lower window, the number of mbufs allocated 201for particular uses, i.e. data, socket structures, etc. 202.It Ic vmstat 203Take over the entire display and show a (rather crowded) compendium 204of statistics related to virtual memory usage, process scheduling, 205device interrupts, system name translation cacheing, disk 206.Tn I/O 207etc. 208.Pp 209The upper left quadrant of the screen shows the number 210of users logged in and the load average over the last one, five, 211and fifteen minute intervals. 212Below this line are statistics on memory utilization. 213The first row of the table reports memory usage only among 214active processes, that is processes that have run in the previous 215twenty seconds. 216The second row reports on memory usage of all processes. 217The first column reports on the number of physical pages 218claimed by processes. 219The second column reports the number of physical pages that 220are devoted to read only text pages. 221The third and fourth columns report the same two figures for 222virtual pages, that is the number of pages that would be 223needed if all processes had all of their pages. 224Finally the last column shows the number of physical pages 225on the free list. 226.Pp 227Below the memory display is a list of the 228average number of processes (over the last refresh interval) 229that are runnable (`r'), in page wait (`p'), 230in disk wait other than paging (`d'), 231sleeping (`s'), and swapped out but desiring to run (`w'). 232Below the queue length listing is a numerical listing and 233a bar graph showing the amount of 234system (shown as `='), interrupt (shown as `+'), user (shown as `>'), 235nice (shown as `-'), and idle time (shown as ` '). 236.Pp 237Below the process display are statistics on name translations. 238It lists the number of names translated in the previous interval, 239the number and percentage of the translations that were 240handled by the system wide name translation cache, and 241the number and percentage of the translations that were 242handled by the per process name translation cache. 243.Pp 244At the bottom left is the disk usage display. 245It reports the number of seeks, transfers, and number 246of kilobyte blocks transferred per second averaged over the 247refresh period of the display (by default, five seconds). 248For some disks it also reports the average milliseconds per seek. 249Note that the system only keeps statistics on at most eight disks 250(this is controlled by the constant DK_NDRIVE in /sys/dkstat.h as 251a kernel compile-time constant). 252.Pp 253Under the date in the upper right hand quadrant are statistics 254on paging and swapping activity. 255The first two columns report the average number of pages 256brought in and out per second over the last refresh interval 257due to page faults and the paging daemon. 258The third and fourth columns report the average number of pages 259brought in and out per second over the last refresh interval 260due to swap requests initiated by the scheduler. 261The first row of the display shows the average 262number of disk transfers per second over the last refresh interval; 263the second row of the display shows the average 264number of pages transferred per second over the last refresh interval. 265.Pp 266Below the paging statistics is a line listing the average number of 267total reclaims ('Rec'), 268intransit blocking page faults (`It'), 269swap text pages found in free list (`F/S'), 270file system text pages found in free list (`F/F'), 271reclaims from free list 272pages freed by the clock daemon (`Fre'), 273and sequential process pages freed (`SFr') 274per second over the refresh interval. 275.Pp 276Below this line are statistics on the average number of 277zero filled pages (`zf') and demand filled text pages (`xf') 278per second over the refresh period. 279The first row indicates the number of requests that were 280resolved, the second row shows the number that were set up, 281and the last row shows the percentage of setup requests that were 282actually used. 283Note that this percentage is usually less than 100%, 284however it may exceed 100% if a large number of requests 285are actually used long after they were set up during a 286period when no new pages are being set up. 287Thus this figure is most interesting when observed over 288a long time period, such as from boot time 289(see below on getting such a display). 290.Pp 291Below the page fill statistics is a column that 292lists the average number of context switches (`Csw'), 293traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'), 294characters output to DZ ports using 295.No pseudo Ns -DMA 296(`Pdm'), 297network software interrupts (`Sof'), 298page faults (`Flt'), pages scanned by the page daemon (`Scn'), 299and revolutions of the page daemon's hand (`Rev') 300per second over the refresh interval. 301.Pp 302Running down the right hand side of the display is a breakdown 303of the interrupts being handled by the system. 304At the top of the list is the total interrupts per second 305over the time interval. 306The rest of the column breaks down the total on a device 307by device basis. 308Only devices that have interrupted at least once since boot time are shown. 309.Pp 310The following commands are specific to the 311.Ic vmstat 312display; the minimum unambiguous prefix may be supplied. 313.Pp 314.Bl -tag -width Ar -compact 315.It Cm boot 316Display cumulative statistics since the system was booted. 317.It Cm run 318Display statistics as a running total from the point this 319command is given. 320.It Cm time 321Display statistics averaged over the refresh interval (the default). 322.It Cm zero 323Reset running statistics to zero. 324.El 325.It Ic netstat 326Display, in the lower window, network connections. By default, 327network servers awaiting requests are not displayed. Each address 328is displayed in the format ``host.port'', with each shown symbolically, 329when possible. It is possible to have addresses displayed numerically, 330limit the display to a set of ports, hosts, and/or protocols 331(the minimum unambiguous prefix may be supplied): 332.Pp 333.Bl -tag -width Ar -compact 334.It Cm all 335Toggle the displaying of server processes awaiting requests (this 336is the equivalent of the 337.Fl a 338flag to 339.Ar netstat 1 ) . 340.It Cm numbers 341Display network addresses numerically. 342.It Cm names 343Display network addresses symbolically. 344.It Ar protocol 345Display only network connections using the indicated protocol 346(currently either ``tcp'' or ``udp''). 347.It Cm ignore Op Ar items 348Do not display information about connections associated with 349the specified hosts or ports. Hosts and ports may be specified 350by name (``vangogh'', ``ftp''), or numerically. Host addresses 351use the Internet dot notation (``128.32.0.9''). Multiple items 352may be specified with a single command by separating them with 353spaces. 354.It Cm display Op Ar items 355Display information about the connections associated with the 356specified hosts or ports. As for 357.Ar ignore , 358.Op Ar items 359may be names or numbers. 360.It Cm show Op Ar ports\&|hosts 361Show, on the command line, the currently selected protocols, 362hosts, and ports. Hosts and ports which are being ignored 363are prefixed with a `!'. If 364.Ar ports 365or 366.Ar hosts 367is supplied as an argument to 368.Cm show , 369then only the requested information will be displayed. 370.It Cm reset 371Reset the port, host, and protocol matching mechanisms to the default 372(any protocol, port, or host). 373.El 374.El 375.Pp 376Commands to switch between displays may be abbreviated to the 377minimum unambiguous prefix; for example, ``io'' for ``iostat''. 378Certain information may be discarded when the screen size is 379insufficient for display. For example, on a machine with 10 380drives the 381.Ic iostat 382bar graph displays only 3 drives on a 24 line terminal. When 383a bar graph would overflow the allotted screen space it is 384truncated and the actual value is printed ``over top'' of the bar. 385.Pp 386The following commands are common to each display which shows 387information about disk drives. These commands are used to 388select a set of drives to report on, should your system have 389more drives configured than can normally be displayed on the 390screen. 391.Pp 392.Bl -tag -width Tx -compact 393.It Cm ignore Op Ar drives 394Do not display information about the drives indicated. Multiple 395drives may be specified, separated by spaces. 396.It Cm display Op Ar drives 397Display information about the drives indicated. Multiple drives 398may be specified, separated by spaces. 399.El 400.Sh FILES 401.Bl -tag -width /etc/networks -compact 402.It Pa /kernel 403For the namelist. 404.It Pa /dev/kmem 405For information in main memory. 406.It Pa /dev/drum 407For information about swapped out processes. 408.It Pa /etc/hosts 409For host names. 410.It Pa /etc/networks 411For network names. 412.It Pa /etc/services 413For port names. 414.El 415.Sh HISTORY 416The 417.Nm systat 418program appeared in 419.Bx 4.3 . 420.Sh BUGS 421Takes 2-10 percent of the cpu. 422Certain displays presume a minimum of 80 characters per line. 423The 424.Ic vmstat 425display looks out of place because it is (it was added in as 426a separate display rather than created as a new program). 427