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