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