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