1.\" $OpenBSD: systat.1,v 1.4 1996/07/08 22:09:43 ccappuc Exp $ 2.\" $NetBSD: systat.1,v 1.6 1996/05/10 23:16:39 thorpej Exp $ 3.\" 4.\" Copyright (c) 1985, 1990, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)systat.1 8.2 (Berkeley) 12/30/93 36.\" 37.Dd December 30, 1993 38.Dt SYSTAT 1 39.Os BSD 4.3 40.Sh NAME 41.Nm systat 42.Nd display system statistics on a crt 43.Sh SYNOPSIS 44.Nm systat 45.Op Fl M Ar core 46.Op Fl N Ar system 47.Op Fl w Ar wait 48.Op Ar display 49.Op Ar refresh-interval 50.Sh DESCRIPTION 51.Nm Systat 52displays various system statistics in a screen oriented fashion 53using the curses screen display library, 54.Xr curses 3 . 55.Pp 56While 57.Nm systat 58is running the screen is usually divided into two windows (an exception 59is the vmstat display which uses the entire screen). The 60upper window depicts the current system load average. The 61information displayed in the lower window may vary, depending on 62user commands. The last line on the screen is reserved for user 63input and error messages. 64.Pp 65By default 66.Nm systat 67displays the processes getting the largest percentage of the processor 68in the lower window. Other displays show swap space usage, disk 69.Tn I/O 70statistics (a la 71.Xr iostat 8 ) , 72virtual memory statistics (a la 73.Xr vmstat 8 ) , 74network ``mbuf'' utilization, and 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 M Ar core 86Extract values associated with the name list from 87.Ar core 88instead of the default 89.Pa /dev/mem . 90.It Fl N Ar system 91Extracr the name list from 92.Ar system 93instead of the default 94.Pa /bsd . 95.It Ar display 96The 97.Ar display 98argument expects to be one of: 99.Ic pigs , 100.Ic iostat , 101.Ic swap , 102.Ic mbufs , 103.Ic vmstat 104or 105.Ic netstat . 106These displays can also be requested interactively and are described in 107full detail below. 108.It Ar refresh-interval 109The 110.Ar refresh-interval 111specifies the screen refresh time interval in seconds. This is provided 112for backwards compatibility, and overrides the 113.Ar refresh-interval 114specified with the 115.Fl w 116flag. 117.El 118.Pp 119Certain characters cause immediate action by 120.Nm systat . 121These are 122.Bl -tag -width Fl 123.It Ic \&^L 124Refresh the screen. 125.It Ic \&^G 126Print the name of the current ``display'' being shown in 127the lower window and the refresh interval. 128.It Ic \&^Z 129Stop 130.Nm systat . 131.It Ic \&: 132Move the cursor to the command line and interpret the input 133line typed as a command. While entering a command the 134current character erase, word erase, and line kill characters 135may be used. 136.El 137.Pp 138The following commands are interpreted by the ``global'' 139command interpreter. 140.Bl -tag -width Fl 141.It Ic help 142Print the names of the available displays on the command line. 143.It Ic load 144Print the load average over the past 1, 5, and 15 minutes 145on the command line. 146.It Ic stop 147Stop refreshing the screen. 148.It Xo 149.Op Ic start 150.Op Ar number 151.Xc 152Start (continue) refreshing the screen. If a second, numeric, 153argument is provided it is interpreted as a refresh interval 154(in seconds). 155Supplying only a number will set the refresh interval to this 156value. 157.It Ic quit 158Exit 159.Nm systat . 160(This may be abbreviated to 161.Ic q . ) 162.El 163.Pp 164The available displays are: 165.Bl -tag -width Ic 166.It Ic pigs 167Display, in the lower window, those processes resident in main 168memory and getting the 169largest portion of the processor (the default display). 170When less than 100% of the 171processor is scheduled to user processes, the remaining time 172is accounted to the ``idle'' process. 173.It Ic iostat 174Display, in the lower window, statistics about processor use 175and disk throughput. Statistics on processor use appear as 176bar graphs of the amount of time executing in user mode (``user''), 177in user mode running low priority processes (``nice''), in 178system mode (``system''), and idle (``idle''). Statistics 179on disk throughput show, for each drive, kilobytes of data transferred, 180number of disk transactions performed, and time spent in disk accesses 181(in milliseconds). This information may be displayed as 182bar graphs or as rows of numbers which scroll downward. Bar 183graphs are shown by default; 184.Pp 185The following commands are specific to the 186.Ic iostat 187display; the minimum unambiguous prefix may be supplied. 188.Pp 189.Bl -tag -width Fl -compact 190.It Cm numbers 191Show the disk 192.Tn I/O 193statistics in numeric form. Values are 194displayed in numeric columns which scroll downward. 195.It Cm bars 196Show the disk 197.Tn I/O 198statistics in bar graph form (default). 199.It Cm secs 200Toggle the display of time in disk activity (the default is to 201not display time). 202.El 203.It Ic swap 204Show information about swap space usage on all the 205swap areas compiled into the kernel. 206The first column is the device name of the partition. 207The next column is the total space available in the partition. 208The 209.Ar Used 210column indicates the total blocks used so far; 211the graph shows the percentage of space in use on each partition. 212If there are more than one swap partition in use, 213a total line is also shown. 214Areas known to the kernel, but not in use are shown as not available. 215.It Ic mbufs 216Display, in the lower window, the number of mbufs allocated 217for particular uses, i.e. data, socket structures, etc. 218.It Ic vmstat 219Take over the entire display and show a (rather crowded) compendium 220of statistics related to virtual memory usage, process scheduling, 221device interrupts, system name translation cacheing, disk 222.Tn I/O 223etc. 224.Pp 225The upper left quadrant of the screen shows the number 226of users logged in and the load average over the last one, five, 227and fifteen minute intervals. 228Below this line are statistics on memory utilization. 229The first row of the table reports memory usage only among 230active processes, that is processes that have run in the previous 231twenty seconds. 232The second row reports on memory usage of all processes. 233The first column reports on the number of physical pages 234claimed by processes. 235The second column reports the number of physical pages that 236are devoted to read only text pages. 237The third and fourth columns report the same two figures for 238virtual pages, that is the number of pages that would be 239needed if all processes had all of their pages. 240Finally the last column shows the number of physical pages 241on the free list. 242.Pp 243Below the memory display is the disk usage display. 244It reports the number of seeks, transfers, number 245of kilobyte blocks transferred per second averaged over the 246refresh period of the display (by default, five seconds), and 247the time spent in disk accesses. 248Note that the system only keeps statistics on at most four disks. 249.Pp 250Below the disk display is a list of the 251average number of processes (over the last refresh interval) 252that are runnable (`r'), in page wait (`p'), 253in disk wait other than paging (`d'), 254sleeping (`s'), and swapped out but desiring to run (`w'). 255Below the queue length listing is a numerical listing and 256a bar graph showing the amount of 257system (shown as `='), user (shown as `>'), 258nice (shown as `-'), and idle time (shown as ` '). 259.Pp 260At the bottom left are statistics on name translations. 261It lists the number of names translated in the previous interval, 262the number and percentage of the translations that were 263handled by the system wide name translation cache, and 264the number and percentage of the translations that were 265handled by the per process name translation cache. 266.Pp 267Under the date in the upper right hand quadrant are statistics 268on paging and swapping activity. 269The first two columns report the average number of pages 270brought in and out per second over the last refresh interval 271due to page faults and the paging daemon. 272The third and fourth columns report the average number of pages 273brought in and out per second over the last refresh interval 274due to swap requests initiated by the scheduler. 275The first row of the display shows the average 276number of disk transfers per second over the last refresh interval; 277the second row of the display shows the average 278number of pages transferred per second over the last refresh interval. 279.Pp 280Below the paging statistics is a line listing the average number of 281total reclaims ('Rec'), 282intransit blocking page faults (`It'), 283swap text pages found in free list (`F/S'), 284file system text pages found in free list (`F/F'), 285reclaims from free list 286pages freed by the clock daemon (`Fre'), 287and sequential process pages freed (`SFr') 288per second over the refresh interval. 289.Pp 290Below this line are statistics on the average number of 291zero filled pages (`zf') and demand filled text pages (`xf') 292per second over the refresh period. 293The first row indicates the number of requests that were 294resolved, the second row shows the number that were set up, 295and the last row shows the percentage of setup requests that were 296actually used. 297Note that this percentage is usually less than 100%, 298however it may exceed 100% if a large number of requests 299are actually used long after they were set up during a 300period when no new pages are being set up. 301Thus this figure is most interesting when observed over 302a long time period, such as from boot time 303(see below on getting such a display). 304.Pp 305Below the page fill statistics is a column that 306lists the average number of context switches (`Csw'), 307traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'), 308characters output to DZ ports using 309.No pseudo Ns -DMA 310(`Pdm'), 311network software interrupts (`Sof'), 312page faults (`Flt'), pages scanned by the page daemon (`Scn'), 313and revolutions of the page daemon's hand (`Rev') 314per second over the refresh interval. 315.Pp 316Running down the right hand side of the display is a breakdown 317of the interrupts being handled by the system. 318At the top of the list is the total interrupts per second 319over the time interval. 320The rest of the column breaks down the total on a device 321by device basis. 322Only devices that have interrupted at least once since boot time are shown. 323.Pp 324The following commands are specific to the 325.Ic vmstat 326display; the minimum unambiguous prefix may be supplied. 327.Pp 328.Bl -tag -width Ar -compact 329.It Cm boot 330Display cumulative statistics since the system was booted. 331.It Cm run 332Display statistics as a running total from the point this 333command is given. 334.It Cm time 335Display statistics averaged over the refresh interval (the default). 336.It Cm zero 337Reset running statistics to zero. 338.El 339.It Ic netstat 340Display, in the lower window, network connections. By default, 341network servers awaiting requests are not displayed. Each address 342is displayed in the format ``host.port'', with each shown symbolically, 343when possible. It is possible to have addresses displayed numerically, 344limit the display to a set of ports, hosts, and/or protocols 345(the minimum unambiguous prefix may be supplied): 346.Pp 347.Bl -tag -width Ar -compact 348.It Cm all 349Toggle the displaying of server processes awaiting requests (this 350is the equivalent of the 351.Fl a 352flag to 353.Ar netstat 1 ) . 354.It Cm numbers 355Display network addresses numerically. 356.It Cm names 357Display network addresses symbolically. 358.It Ar protocol 359Display only network connections using the indicated protocol 360(currently either ``tcp'' or ``udp''). 361.It Cm ignore Op Ar items 362Do not display information about connections associated with 363the specified hosts or ports. Hosts and ports may be specified 364by name (``vangogh'', ``ftp''), or numerically. Host addresses 365use the Internet dot notation (``128.32.0.9''). Multiple items 366may be specified with a single command by separating them with 367spaces. 368.It Cm display Op Ar items 369Display information about the connections associated with the 370specified hosts or ports. As for 371.Ar ignore , 372.Op Ar items 373may be names or numbers. 374.It Cm show Op Ar ports\&|hosts 375Show, on the command line, the currently selected protocols, 376hosts, and ports. Hosts and ports which are being ignored 377are prefixed with a `!'. If 378.Ar ports 379or 380.Ar hosts 381is supplied as an argument to 382.Cm show , 383then only the requested information will be displayed. 384.It Cm reset 385Reset the port, host, and protocol matching mechanisms to the default 386(any protocol, port, or host). 387.El 388.El 389.Pp 390Commands to switch between displays may be abbreviated to the 391minimum unambiguous prefix; for example, ``io'' for ``iostat''. 392Certain information may be discarded when the screen size is 393insufficient for display. For example, on a machine with 10 394drives the 395.Ic iostat 396bar graph displays only 3 drives on a 24 line terminal. When 397a bar graph would overflow the allotted screen space it is 398truncated and the actual value is printed ``over top'' of the bar. 399.Pp 400The following commands are common to each display which shows 401information about disk drives. These commands are used to 402select a set of drives to report on, should your system have 403more drives configured than can normally be displayed on the 404screen. 405.Pp 406.Bl -tag -width Tx -compact 407.It Cm ignore Op Ar drives 408Do not display information about the drives indicated. Multiple 409drives may be specified, separated by spaces. 410.It Cm display Op Ar drives 411Display information about the drives indicated. Multiple drives 412may be specified, separated by spaces. 413.El 414.Sh FILES 415.Bl -tag -width /etc/networks -compact 416.It Pa /bsd 417For the namelist. 418.It Pa /dev/kmem 419For information in main memory. 420.It Pa /dev/drum 421For information about swapped out processes. 422.It Pa /etc/hosts 423For host names. 424.It Pa /etc/networks 425For network names. 426.It Pa /etc/services 427For port names. 428.El 429.Sh HISTORY 430The 431.Nm systat 432program appeared in 433.Bx 4.3 . 434.Sh BUGS 435Takes 2-10 percent of the cpu. 436Certain displays presume a minimum of 80 characters per line. 437The 438.Ic vmstat 439display looks out of place because it is (it was added in as 440a separate display rather than created as a new program). 441