1.\" $NetBSD: systat.1,v 1.48 2017/07/03 21:34:21 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)systat.1 8.2 (Berkeley) 12/30/93 31.\" 32.Dd November 16, 2016 33.Dt SYSTAT 1 34.Os 35.Sh NAME 36.Nm systat 37.Nd display system statistics in a full-screen view 38.Sh SYNOPSIS 39.Nm 40.Op Fl bn 41.Op Fl M Ar core 42.Op Fl N Ar system 43.Op Fl t Ar turns 44.Op Fl w Ar wait 45.Op Ar display 46.Op Ar refresh-interval 47.Sh DESCRIPTION 48.Nm 49displays various system statistics in a screen oriented fashion 50using the curses screen display library, 51.Xr curses 3 . 52.Pp 53While 54.Nm 55is running the screen is usually divided into two windows (an exception 56is the vmstat display which uses the entire screen). 57The upper window depicts the current system load average. 58The information displayed in the lower window may vary, depending on 59user commands. 60The last line on the screen is reserved for user input and error messages. 61.Pp 62By default 63.Nm 64displays the processes getting the largest percentage of the processor 65in the lower window. 66Other displays show more detailed process information, 67swap space usage, 68disk usage statistics (a la 69.Xr df 1 ) , 70disk 71.Tn I/O 72statistics (a la 73.Xr iostat 8 ) , 74virtual memory statistics (a la 75.Xr vmstat 1 ) , 76network ``mbuf'' utilization, network 'ifstat' traffic, 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. 83This allows 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 b 98Show the chosen display once and exit. 99.It Fl n 100Do not resolve IP addresses into string hostnames 101.Pq FQDNs 102on 103.Ic netstat . 104It has the same effect as 105.Ic numbers 106subcommand in 107.Ic netstat . 108.It Fl w Ar wait 109See 110.Ar refresh-interval . 111.It Fl t Ar turns 112How many refreshes to show each screen in 'all' display mode. 113.It Ar display 114The 115.Ar display 116argument expects to be one of: 117.Ic all , 118.Ic bufcache , 119.Ic df , 120.Ic ifstat , 121.Ic inet.icmp , 122.Ic inet.ip , 123.Ic inet.tcp , 124.Ic inet.tcpsyn , 125.Ic inet6.ip6 , 126.Ic iostat , 127.Ic mbufs , 128.Ic netstat , 129.Ic pigs , 130.Ic ps , 131.Ic swap , 132.Ic syscall 133or 134.Ic vmstat . 135These displays can also be requested interactively and are described in 136full detail below. 137.It Ar refresh-interval 138The 139.Ar refresh-interval 140specifies the screen refresh time interval in seconds. 141This is provided for backwards compatibility, and overrides the 142.Ar refresh-interval 143specified with the 144.Fl w 145flag. 146.El 147.Pp 148Certain characters cause immediate action by 149.Nm . 150These are 151.Bl -tag -width Fl 152.It Ic \&^L 153Refresh the screen. 154.It Ic \&^G 155Print the name of the current ``display'' being shown in 156the lower window and the refresh interval. 157.It Ic \&^Z 158Stop 159.Nm . 160.It Ic \&? , Ic h 161Print the names of the available displays on the command line. 162.It Ic \&: 163Move the cursor to the command line and interpret the input 164line typed as a command. 165While entering a command the current character erase, word erase, 166and line kill characters may be used. 167.El 168.Pp 169The following commands are interpreted by the ``global'' 170command interpreter. 171.Bl -tag -width Fl 172.It Ic help Ar key 173Print the names of the available displays on the command line. 174It will print long names as 175.Dq Ic inet.* . 176To print items under 177.Dq Ic inet , 178give 179.Ic inet 180as 181.Ar key . 182.It Ic load 183Print the load average over the past 1, 5, and 15 minutes 184on the command line. 185.It Ic stop 186Stop refreshing the screen. 187.It Oo Ic start Oc Oo Ar number Oc 188Start (continue) refreshing the screen. 189If a second, numeric, argument is provided it is interpreted as a 190refresh interval in seconds. 191Supplying only a number will set the refresh interval to this 192value. 193.It Ic quit 194Exit 195.Nm . 196(This may be abbreviated to 197.Ic q . ) 198.El 199.Pp 200The available displays are: 201.Bl -tag -width Ic 202.It Ic all 203Cycle through all displays automatically. 204At each display, wait some 205refresh-turns, then switch to the next display. 206Duration of one refresh-turn is adjustable with the 207.Fl w 208option, number of refresh-turns can be changed with the 209.Fl t 210option. 211.It Ic bufcache 212Display, in the lower window, statistics about the file system buffers. 213Statistics for each file system that has active buffers include the number 214of buffers for that file system, the number of active kilobytes in those 215buffers and the total size of the buffers for that file system. 216.It Ic df 217Lists disk usage statistics for all filesystems, 218including the available free space as well as a bar 219graph indicating the used capacity. 220.Pp 221The following commands are specific to the 222.Ic df 223display: 224.Pp 225.Bl -tag -width Fl -compact 226.It Cm all 227Displays information for all filesystems, including 228kernfs, procfs and null-mounts. 229.It Cm some 230Suppress information about procfs, kernfs and null-mounts (default). 231.El 232.It Ic ifstat 233Display the network traffic going through active interfaces on the 234system. 235Idle interfaces will not be displayed until they receive some 236traffic. 237.Pp 238For each interface being displayed, the current, peak and total 239statistics are displayed for incoming and outgoing traffic. 240By default, 241the 242.Ic ifstat 243display will automatically scale the units being used so that they are 244in a human-readable format. 245The scaling units used for the current and 246peak 247traffic columns can be altered by the 248.Ic scale 249command. 250.Bl -tag -width ".Cm scale Op Ar units" 251.It Cm scale Op Ar units 252Modify the scale used to display the current and peak traffic over all 253interfaces. 254The following units are recognised: kbit, kbyte, mbit, 255mbyte, gbit, gbyte and auto. 256.It Cm pps 257Show statistics in packets per second instead of bytes/bits per second. 258A subsequent call of 259.Ic pps 260switches this mode off. 261.It Cm match Op Ar patterns 262Display only interfaces that match pattern provided as an argument. 263Patterns should be in shell syntax separated by whitespaces or commas. 264If this command is called without arguments then all interfaces are displayed. 265For example: 266.Pp 267.Dl match re0, bge1 268.Pp 269This will display re0 and bge1 interfaces. 270.Pp 271.Dl match re*, bge*, lo0 272.Pp 273This will display all 274.Ic re 275interfaces, all 276.Ic bge 277interfaces and the loopback interface. 278.El 279.Pp 280.It Ic inet.icmp 281Display ICMP statistics. 282.It Ic inet.ip 283Display IPv4 and UDP statistics. 284.It Ic inet.tcp 285Display TCP statistics. 286.It Ic inet.tcpsyn 287Display statistics about the 288.Tn TCP 289``syncache''. 290.It Ic inet6.ip6 291Display IPv6 statistics. 292.It Ic iostat 293Display, in the lower window, statistics about processor use 294and disk throughput. 295Statistics on processor use appear as bar graphs of the amount of 296time executing in user mode (``user''), in user mode running low 297priority processes (``nice''), in system mode (``system''), and 298idle (``idle''). 299Statistics on disk throughput show, for each drive, kilobytes of 300data transferred, number of disk transactions performed, and time 301spent in disk accesses in milliseconds. 302This information may be displayed as bar graphs or as rows of 303numbers which scroll downward. 304Bar graphs are shown by default; 305.Pp 306The following commands are specific to the 307.Ic iostat 308display; the minimum unambiguous prefix may be supplied. 309.Pp 310.Bl -tag -width Fl -compact 311.It Cm numbers 312Show the disk 313.Tn I/O 314statistics in numeric form. 315Values are 316displayed in numeric columns which scroll downward. 317.It Cm bars 318Show the disk 319.Tn I/O 320statistics in bar graph form (default). 321.It Cm secs 322Toggle the display of time in disk activity (the default is to 323not display time). 324.It Cm all 325Show the read and write statistics combined (default). 326.It Cm rw 327Show the read and write statistics separately. 328.El 329.It Ic mbufs 330Display, in the lower window, the number of mbufs allocated 331for particular uses, i.e. data, socket structures, etc. 332.It Ic netstat 333Display, in the lower window, network connections. 334By default, network servers awaiting requests are not displayed. 335Each address is displayed in the format ``host.port'', with each 336shown symbolically, when possible. 337It is possible to have addresses displayed numerically, 338limit the display to a set of ports, hosts, and/or protocols 339(the minimum unambiguous prefix may be supplied): 340.Pp 341.Bl -tag -width Ar -compact 342.It Cm all 343Toggle the displaying of server processes awaiting requests (this 344is the equivalent of the 345.Fl a 346flag to 347.Ar netstat 1 ) . 348.It Cm numbers 349Display network addresses numerically. 350.It Cm names 351Display network addresses symbolically. 352.It Ar protocol 353Display only network connections using the indicated protocol 354(currently either ``tcp'' or ``udp''). 355.It Cm ignore Op Ar items 356Do not display information about connections associated with 357the specified hosts or ports. 358Hosts and ports may be specified by name (``vangogh'', ``ftp''), 359or numerically. 360Host addresses use the Internet dot notation (``128.32.0.9''). 361Multiple items may be specified with a single command by separating 362them with spaces. 363.It Cm display Op Ar items 364Display information about the connections associated with the 365specified hosts or ports. 366As for 367.Ar ignore , 368.Op Ar items 369may be names or numbers. 370.It Cm show Op Ar ports\&|hosts 371Show, on the command line, the currently selected protocols, 372hosts, and ports. 373Hosts and ports which are being ignored are prefixed with a `!'. 374If 375.Ar ports 376or 377.Ar hosts 378is supplied as an argument to 379.Cm show , 380then only the requested information will be displayed. 381.It Cm reset 382Reset the port, host, and protocol matching mechanisms to the default 383(any protocol, port, or host). 384.El 385.It Ic pigs 386Display, in the lower window, those processes which are getting the 387largest portion of the processor (the default display). 388When less than 100% of the 389processor is scheduled to user processes, the remaining time 390is accounted to the ``idle'' process. 391.It Ic ps 392Display, in the lower window, the same information provided 393by the command 394.Xr ps 1 395with the flags 396.Fl aux . 397.Pp 398The following command is specific to the 399.Ic ps 400display; the minimum unambiguous prefix may be supplied. 401.Pp 402.Bl -tag -width Fl -compact 403.It Cm user Ar name 404Limit the list of processes displayed to those owned by user 405.Ar name . 406If 407.Ar name 408is specified as `+', processes owned by any user are displayed (default). 409.El 410.It Ic swap 411Show information about swap space usage on all the 412swap areas configured with 413.Xr swapctl 8 . 414The first column is the device name of the partition. 415The next column is the total space available in the partition. 416The 417.Ar Used 418column indicates the total blocks used so far; 419the graph shows the percentage of space in use on each partition. 420If there are more than one swap partition in use, 421a total line is also shown. 422Areas known to the kernel, but not in use are shown as not available. 423.It Ic syscall 424Show per system call statistics. 425The display consists of several columns of system call name and counts. 426.Pp 427In order to stop entries moving around the screen too much, an infinite 428response filter is applied to the values before they are sorted. 429.Pp 430The following commands are specific to the 431.Ic syscall 432display: 433.Pp 434.Bl -tag -width Ar -compact 435.It Ic sort Ic name 436Sort display by the syscall name (default). 437.It Ic sort Ic count 438Sort display by the count of calls or time spent in the calls. 439.It Ic sort Ic syscall 440Sort display be syscall number. 441.It Ic show Ic count 442Show the number of times the system call has be called (default). 443.It Ic show Ic time 444Show the average amount of time (in arbitrary units) spent in a call of 445the syscall. 446.El 447.It Ic vmstat 448Take over the entire display and show a (rather crowded) compendium 449of statistics related to virtual memory usage, process scheduling, 450device interrupts, system name translation caching, disk 451.Tn I/O 452etc. 453.Pp 454The upper left quadrant of the screen shows the number 455of users logged in and the load average over the last one, five, 456and fifteen minute intervals. 457Below this is a list of the 458average number of processes (over the last refresh interval) 459that are runnable (`r'), in page wait (`p'), 460in disk wait other than paging (`d'), sleeping (`s'). 461Below the queue length listing is a numerical listing and 462a bar graph showing the amount of 463system (shown as `='), user (shown as `>'), 464nice (shown as `-'), and idle time (shown as ` '). 465.Pp 466To the right of the process statistics is a column that 467lists the average number of context switches (`Csw'), 468traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'), 469network software interrupts (`Sof'), 470page faults (`Flt'). 471.Pp 472Below this are statistics on memory utilization. 473The first row of the table reports memory usage only among 474active processes, that is processes that have run in the previous 475twenty seconds. 476The second row reports on memory usage of all processes. 477The first column reports on the number of physical pages 478claimed by processes. 479The second column reports the number of pages of memory and swap. 480The third column gives the number of pages of free memory and swap. 481.Pp 482Below the memory display are statistics on name translations. 483It lists the number of names translated in the previous interval, 484the number and percentage of the translations that were 485handled by the system wide name translation cache, and 486the number and percentage of the translations that were 487handled by the per process name translation cache. 488.Pp 489At the bottom left is the disk usage display. 490It reports the number of seeks, transfers, number 491of kilobyte blocks transferred per second averaged over the 492refresh period of the display (by default, five seconds), and 493the time spent in disk accesses. 494If there are more than five disks, and the terminal window has more 495than 24 lines, the disks display will be flipped so that more 496of the disk statistics are visible. 497.Pp 498Under the date in the upper right hand quadrant are statistics 499on paging and swapping activity. 500The first two columns report the average number of pages 501brought in and out per second over the last refresh interval 502due to page faults and the paging daemon. 503The third and fourth columns report the average number of pages 504brought in and out per second over the last refresh interval 505due to swap requests initiated by the scheduler. 506The first row of the display shows the average 507number of disk transfers per second over the last refresh interval; 508the second row of the display shows the average 509number of pages transferred per second over the last refresh interval. 510.Pp 511Below the paging statistics is another columns of paging data. 512From top to bottom, these represent average numbers of copy on write faults 513(`cow'), object cache lookups (`objlk'), object cache hits (`objht'), 514pages zero filled on demand (`zfodw'), number zfod's created (`nzfod'), 515percentage of zfod's used (`%zfod'), number of kernel pages (`kern'), 516number of wired pages (`wire'), number of active pages (`act'), number 517of inactive pages (`inact'), number of free pages (`free'), pages freed 518by daemon (`daefr'), pages freed by exiting processes (`prcfr'), number 519of pages reactivated from freelist (`react'), scans in page out daemon 520(`scan'), revolutions of the hand (`hdrev'), and in-transit blocking page 521faults (`intrn'), per second over the refresh period. 522Note that the `%zfod' percentage is usually less than 100%, 523however it may exceed 100% if a large number of requests 524are actually used long after they were set up during a 525period when no new pages are being set up. 526Thus this figure is most interesting when observed over 527a long time period, such as from boot time 528(see below on getting such a display). 529.Pp 530To the left of the column of paging statistics is a breakdown 531of the interrupts being handled by the system. 532At the top of the list is the total interrupts per second 533over the time interval. 534The rest of the column breaks down the total on a device 535by device basis. 536Only devices that have interrupted at least once since boot time are shown. 537.El 538.Pp 539Commands to switch between displays may be abbreviated to the 540minimum unambiguous prefix; for example, ``io'' for ``iostat''. 541Certain information may be discarded when the screen size is 542insufficient for display. 543For example, on a machine with 10 drives the 544.Ic iostat 545bar graph displays only 3 drives on a 24 line terminal. 546When a bar graph would overflow the allotted screen space it is 547truncated and the actual value is printed ``over top'' of the bar. 548.Pp 549The following commands are common to each display which shows 550information about disk drives. 551These commands are used to select a set of drives to report on, 552should your system have more drives configured than can normally 553be displayed on the screen. 554Drives may be specified as drive names or as patterns specified in the 555notation described by 556.Xr fnmatch 3 . 557.Pp 558.Bl -tag -width Ar -compact 559.It Cm display Op Ar drives 560Display information about the drives indicated. 561Multiple drives may be specified, separated by spaces. 562.It Cm ignore Op Ar drives 563Do not display information about the drives indicated. 564Multiple drives may be specified, separated by spaces. 565.It Cm drives Op Ar drives 566With no arguments, display a list of available drives. 567With arguments, replace the list of currently displayed drives 568with the ones specified. 569.El 570.Pp 571The following commands are specific to the 572.Ic inet.* , 573.Ic inet6.* , 574.Ic syscall 575and 576.Ic vmstat 577displays; the minimum unambiguous prefix may be supplied. 578.Pp 579.Bl -tag -width Ar -compact 580.It Cm boot 581Display cumulative statistics since the system was booted. 582.It Cm run 583Display statistics as a running total from the point this 584command is given. 585.It Cm time 586Display statistics averaged over the refresh interval (the default). 587.It Cm zero 588Reset running statistics to zero. 589.El 590.Sh FILES 591.Bl -tag -width /etc/networks -compact 592.It Pa /netbsd 593For the namelist. 594.It Pa /dev/kmem 595For information in main memory. 596.It Pa /etc/hosts 597For host names. 598.It Pa /etc/networks 599For network names. 600.It Pa /etc/services 601For port names. 602.El 603.Sh NOTES 604Much of the information that 605.Nm 606.Ic vmstat 607uses is obtained from 608.Cm struct vmmeter cnt . 609.Sh SEE ALSO 610.Xr df 1 , 611.Xr netstat 1 , 612.Xr ps 1 , 613.Xr top 1 , 614.Xr vmstat 1 , 615.Xr iostat 8 , 616.Xr pstat 8 617.Sh HISTORY 618The 619.Nm 620program appeared in 621.Bx 4.3 . 622.Sh BUGS 623Consumes CPU resources and thus may skew statistics. 624.Pp 625Certain displays presume a minimum of 80 characters per line. 626.Pp 627The 628.Ic vmstat 629display looks out of place because it is (it was added in as 630a separate display from what used to be a different program). 631.Pp 632The 633.Fl b 634option requires a real terminal and could be converted to 635simply output to standard output. 636