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