1.\" $NetBSD: systat.1,v 1.51 2018/12/28 12:21:53 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 December 26, 2018 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 I/O statistics (a la 71.Xr iostat 8 ) , 72virtual memory statistics (a la 73.Xr vmstat 1 ) , 74network ``mbuf'' utilization, network 'ifstat' traffic, and network connections (a la 75.Xr netstat 1 ) . 76.Pp 77Input is interpreted at two different levels. 78A ``global'' command interpreter processes all keyboard input. 79If this command interpreter fails to recognize a command, the 80input line is passed to a per-display command interpreter. 81This allows each display to have certain display-specific commands. 82.Pp 83Command line options: 84.Bl -tag -width "refresh_interval" 85.It Fl M Ar core 86Extract values associated with the name list from 87.Ar core 88instead of the default 89.Pa /dev/mem . 90.It Fl N Ar system 91Extract the name list from 92.Ar system 93instead of the default 94.Pa /netbsd . 95.It Fl b 96Show the chosen display once and exit. 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 refreshes 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 df , 118.Ic ifstat , 119.Ic inet.icmp , 120.Ic inet.ip , 121.Ic inet.tcp , 122.Ic inet.tcpsyn , 123.Ic inet6.ip6 , 124.Ic iostat , 125.Ic mbufs , 126.Ic netstat , 127.Ic pigs , 128.Ic ps , 129.Ic swap , 130.Ic syscall 131or 132.Ic vmstat . 133These displays can also be requested interactively and are described in 134full detail below. 135.It Ar refresh-interval 136The 137.Ar refresh-interval 138specifies the screen refresh time interval in seconds. 139This is provided for backwards compatibility, and overrides the 140.Ar refresh-interval 141specified with the 142.Fl w 143flag. 144.El 145.Pp 146Certain characters cause immediate action by 147.Nm . 148These are 149.Bl -tag -width Fl 150.It Ic \&^L 151Refresh the screen. 152.It Ic \&^G 153Print the name of the current ``display'' being shown in 154the lower window and the refresh interval. 155.It Ic \&^Z 156Stop 157.Nm . 158.It Ic \&? , Ic h 159Print the names of the available displays on the command line. 160.It Ic \&: 161Move the cursor to the command line and interpret the input 162line typed as a command. 163While entering a command the current character erase, word erase, 164and line kill characters may be used. 165.El 166.Pp 167The following commands are interpreted by the ``global'' 168command interpreter. 169.Bl -tag -width Fl 170.It Ic help Ar key 171Print the names of the available displays on the command line. 172It will print long names as 173.Dq Ic inet.* . 174To print items under 175.Dq Ic inet , 176give 177.Ic inet 178as 179.Ar key . 180.It Ic load 181Print the load average over the past 1, 5, and 15 minutes 182on the command line. 183.It Ic stop 184Stop refreshing the screen. 185.It Oo Ic start Oc Oo Ar number Oc 186Start (continue) refreshing the screen. 187If a second, numeric, argument is provided it is interpreted as a 188refresh interval in seconds. 189Supplying only a number will set the refresh interval to this 190value. 191.It Ic quit 192Exit 193.Nm . 194(This may be abbreviated to 195.Ic q . ) 196.El 197.Pp 198The available displays are: 199.Bl -tag -width Ic 200.It Ic all 201Cycle through all displays automatically. 202At 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 df 215Lists disk usage statistics for all filesystems, 216including the available free space as well as a bar 217graph indicating the used capacity. 218.Pp 219The following commands are specific to the 220.Ic df 221display: 222.Pp 223.Bl -tag -width Fl -compact 224.It Cm all 225Displays information for all filesystems, including 226kernfs, procfs and null-mounts. 227.It Cm some 228Suppress information about procfs, kernfs and null-mounts (default). 229.El 230.It Ic ifstat 231Display the network traffic going through active interfaces on the 232system. 233Idle interfaces will not be displayed until they receive some 234traffic. 235.Pp 236For each interface being displayed, the current, peak and total 237statistics are displayed for incoming and outgoing traffic. 238By default, 239the 240.Ic ifstat 241display will automatically scale the units being used so that they are 242in a human-readable format. 243The scaling units used for the current and 244peak 245traffic columns can be altered by the 246.Ic scale 247command. 248.Bl -tag -width ".Cm scale Op Ar units" 249.It Cm scale Op Ar units 250Modify the scale used to display the current and peak traffic over all 251interfaces. 252The following units are recognised: kbit, kbyte, mbit, 253mbyte, gbit, gbyte and auto. 254.It Cm pps 255Show statistics in packets per second instead of bytes/bits per second. 256A subsequent call of 257.Ic pps 258switches this mode off. 259.It Cm match Op Ar patterns 260Display only interfaces that match pattern provided as an argument. 261Patterns should be in shell syntax separated by whitespaces or commas. 262If this command is called without arguments then all interfaces are displayed. 263For example: 264.Pp 265.Dl match re0, bge1 266.Pp 267This will display re0 and bge1 interfaces. 268.Pp 269.Dl match re*, bge*, lo0 270.Pp 271This will display all 272.Ic re 273interfaces, all 274.Ic bge 275interfaces and the loopback interface. 276.El 277.It Ic inet.icmp 278Display ICMP statistics. 279.It Ic inet.ip 280Display IPv4 and UDP statistics. 281.It Ic inet.tcp 282Display TCP statistics. 283.It Ic inet.tcpsyn 284Display statistics about the TCP ``syncache''. 285.It Ic inet6.ip6 286Display IPv6 statistics. 287.It Ic iostat 288Display, in the lower window, statistics about processor use 289and disk throughput. 290Statistics on processor use appear as bar graphs of the amount of 291time executing in user mode (``user''), in user mode running low 292priority processes (``nice''), in system mode (``system''), and 293idle (``idle''). 294Statistics on disk throughput show, for each drive, kilobytes of 295data transferred, number of disk transactions performed, and time 296spent in disk accesses in milliseconds. 297This information may be displayed as bar graphs or as rows of 298numbers which scroll downward. 299Bar graphs are shown by default; 300.Pp 301The following commands are specific to the 302.Ic iostat 303display; the minimum unambiguous prefix may be supplied. 304.Pp 305.Bl -tag -width Fl -compact 306.It Cm numbers 307Show the disk I/O statistics in numeric form. 308Values are 309displayed in numeric columns which scroll downward. 310.It Cm bars 311Show the disk I/O statistics in bar graph form (default). 312.It Cm secs 313Toggle the display of time in disk activity (the default is to 314not display time). 315.It Cm all 316Show the read and write statistics combined (default). 317.It Cm rw 318Show the read and write statistics separately. 319.El 320.It Ic mbufs 321Display, in the lower window, the number of mbufs allocated 322for particular uses, i.e. data, socket structures, etc. 323.It Ic netstat 324Display, in the lower window, network connections. 325By default, network servers awaiting requests are not displayed. 326Each address is displayed in the format ``host.port'', with each 327shown symbolically, when possible. 328It is possible to have addresses displayed numerically, 329limit the display to a set of ports, hosts, and/or protocols 330(the minimum unambiguous prefix may be supplied): 331.Pp 332.Bl -tag -width Ar -compact 333.It Cm all 334Toggle the displaying of server processes awaiting requests (this 335is the equivalent of the 336.Fl a 337flag to 338.Ar netstat 1 ) . 339.It Cm numbers 340Display network addresses numerically. 341.It Cm names 342Display network addresses symbolically. 343.It Ar protocol 344Display only network connections using the indicated protocol 345(currently either ``tcp'' or ``udp''). 346.It Cm ignore Op Ar items 347Do not display information about connections associated with 348the specified hosts or ports. 349Hosts and ports may be specified by name (``vangogh'', ``ftp''), 350or numerically. 351Host addresses use the Internet dot notation (``128.32.0.9''). 352Multiple items may be specified with a single command by separating 353them with spaces. 354.It Cm display Op Ar items 355Display information about the connections associated with the 356specified hosts or ports. 357As for 358.Ar ignore , 359.Op Ar items 360may be names or numbers. 361.It Cm show Op Ar ports\&|hosts 362Show, on the command line, the currently selected protocols, 363hosts, and ports. 364Hosts and ports which are being ignored are prefixed with a `!'. 365If 366.Ar ports 367or 368.Ar hosts 369is supplied as an argument to 370.Cm show , 371then only the requested information will be displayed. 372.It Cm reset 373Reset the port, host, and protocol matching mechanisms to the default 374(any protocol, port, or host). 375.El 376.It Ic pigs 377Display, in the lower window, those processes which are getting the 378largest portion of the processor (the default display). 379When less than 100% of the 380processor is scheduled to user processes, the remaining time 381is accounted to the ``idle'' process. 382.It Ic ps 383Display, in the lower window, the same information provided 384by the command 385.Xr ps 1 386with the flags 387.Fl aux . 388.Pp 389The following command is specific to the 390.Ic ps 391display; the minimum unambiguous prefix may be supplied. 392.Pp 393.Bl -tag -width Fl -compact 394.It Cm user Ar name 395Limit the list of processes displayed to those owned by user 396.Ar name . 397If 398.Ar name 399is specified as `+', processes owned by any user are displayed (default). 400.El 401.It Ic swap 402Show information about swap space usage on all the 403swap areas configured with 404.Xr swapctl 8 . 405The first column is the device name of the partition. 406The next column is the total space available in the partition. 407The 408.Ar Used 409column indicates the total blocks used so far; 410the graph shows the percentage of space in use on each partition. 411If there are more than one swap partition in use, 412a total line is also shown. 413Areas known to the kernel, but not in use are shown as not available. 414.It Ic syscall 415Show per system call statistics. 416The display consists of several columns of system call name and counts. 417.Pp 418In order to stop entries moving around the screen too much, an infinite 419response filter is applied to the values before they are sorted. 420.Pp 421The following commands are specific to the 422.Ic syscall 423display: 424.Pp 425.Bl -tag -width Ar -compact 426.It Ic sort Ic name 427Sort display by the syscall name (default). 428.It Ic sort Ic count 429Sort display by the count of calls or time spent in the calls. 430.It Ic sort Ic syscall 431Sort display be syscall number. 432.It Ic show Ic count 433Show the number of times the system call has be called (default). 434.It Ic show Ic time 435Show the average amount of time (in arbitrary units) spent in a call of 436the syscall. 437.El 438.It Ic vmstat 439Take over the entire display and show a (rather crowded) compendium 440of statistics related to virtual memory usage, process scheduling, 441device interrupts, system name translation caching, disk I/O etc. 442.Pp 443The upper left quadrant of the screen shows the number 444of users logged in and the load average over the last one, five, 445and fifteen minute intervals. 446Below this are statistics on memory utilization. 447The first row of the table reports memory usage only among 448active processes, that is processes that have run in the previous 449twenty seconds. 450The second row reports on memory usage of all processes. 451The first column reports on the number of physical pages 452claimed by processes. 453The second column reports the number of physical pages that 454are devoted to read only text pages. 455The third and fourth columns report the same two figures for 456virtual pages, that is the number of pages that would be 457needed if all processes had all of their pages. 458Finally the last column shows the number of physical pages 459on the free list. 460.Pp 461Below the memory display is a list of the 462average number of processes (over the last refresh interval) 463that are runnable (`r'), in page wait (`p'), 464in disk wait other than paging (`d'), sleeping (`s'). 465Below the queue length listing is a numerical listing and 466a bar graph showing the amount of 467system (shown as `='), user (shown as `>'), 468nice (shown as `-'), and idle time (shown as ` '). 469.Pp 470To the right of the process statistics is a column that 471lists the average number of context switches (`Csw'), 472traps (`Traps'; includes page faults), system calls (`SysCa'), interrupts (`Intr'), 473network software interrupts (`Soft'), 474page faults (`Fault'). 475.Pp 476Below this are statistics on memory utilization. 477The first row of the table reports memory usage only among 478active processes, that is processes that have run in the previous 479twenty seconds. 480The second row reports on memory usage of all processes. 481The first column reports on the number of physical pages 482claimed by processes. 483The second column reports the number of pages of memory and swap. 484The third column gives the number of pages of free memory and swap. 485.Pp 486Below the memory display are statistics on name translations. 487It lists the number of names translated in the previous interval, 488the number and percentage of the translations that were 489handled by the system wide name translation cache, and 490the number and percentage of the translations that were 491handled by the per process name translation cache. 492.Pp 493At the bottom left is the disk usage display. 494It reports the number of seeks, transfers, number 495of kilobyte blocks transferred per second averaged over the 496refresh period of the display (by default, five seconds), and 497the time spent in disk accesses. 498If there are more than five disks, and the terminal window has more 499than 24 lines, the disks display will be flipped so that more 500of the disk statistics are visible. 501.Pp 502Under the date in the upper right hand quadrant are statistics 503on paging and swapping activity. 504The first two columns report the average number of pages 505brought in and out per second over the last refresh interval 506due to page faults and the paging daemon. 507The third and fourth columns report the average number of pages 508brought in and out per second over the last refresh interval 509due to swap requests initiated by the scheduler. 510The first row of the display shows the average 511number of disk transfers per second over the last refresh interval; 512the second row of the display shows the average 513number of pages transferred per second over the last refresh interval. 514.Pp 515Below the paging statistics is another columns of paging data. 516From top to bottom, these represent: 517.Pp 518.Bl -tag -width Fl -compact 519.It Sq Ic forks 520number of 521.Fn fork 522calls 523.It Sq Ic fkppw 524number of 525.Fn fork 526calls where parent waits 527.It Sq Ic fksvm 528number of 529.Fn fork 530calls where vmspace is shared 531.It Sq Ic pwait 532number of times fault had to wait on a page 533.It Sq Ic relck 534number of times 535.Fn uvmfault_relock 536is called 537.It Sq Ic rlkok 538number of times 539.Fn uvmfault_relock 540is a success 541.It Sq Ic noram 542number of times fault was out of RAM 543.It Sq Ic ndcpy 544number of times fault clears ``needs copy'' 545.It Sq Ic fltcp 546number of times fault promotes with copy (2b) 547.It Sq Ic zfod 548number of times fault promotes with zerofill (2b) 549.It Sq Ic cow 550number of times faulted for anonymous for Copy-On-Write (case 1b) 551.It Sq Ic fmin 552min number of free pages 553.It Sq Ic ftarg 554target number of free pages 555.It Sq Ic itarg 556target number of inactive pages 557.It Sq Ic flnan 558number of times fault was out of anonymous pages 559.It Sq Ic pdfre 560number of pages daemon freed since boot 561.It Sq Ic pdscn 562number of pages daemon scanned since boot 563.El 564.Pp 565Note that the `%zfod' percentage is usually less than 100%, 566however it may exceed 100% if a large number of requests 567are actually used long after they were set up during a 568period when no new pages are being set up. 569Thus this figure is most interesting when observed over 570a long time period, such as from boot time 571(see below on getting such a display). 572.Pp 573To the left of the column of paging statistics is a breakdown 574of the interrupts being handled by the system. 575At the top of the list is the total interrupts per second 576over the time interval. 577The rest of the column breaks down the total on a device 578by device basis. 579Only devices that have interrupted at least once since boot time are shown. 580.El 581.Pp 582Commands to switch between displays may be abbreviated to the 583minimum unambiguous prefix; for example, ``io'' for ``iostat''. 584Certain information may be discarded when the screen size is 585insufficient for display. 586For example, on a machine with 10 drives the 587.Ic iostat 588bar graph displays only 3 drives on a 24 line terminal. 589When a bar graph would overflow the allotted screen space it is 590truncated and the actual value is printed ``over top'' of the bar. 591.Pp 592The following commands are common to each display which shows 593information about disk drives. 594These commands are used to select a set of drives to report on, 595should your system have more drives configured than can normally 596be displayed on the screen. 597Drives may be specified as drive names or as patterns specified in the 598notation described by 599.Xr fnmatch 3 . 600.Pp 601.Bl -tag -width Ar -compact 602.It Cm display Op Ar drives 603Display information about the drives indicated. 604Multiple drives may be specified, separated by spaces. 605.It Cm ignore Op Ar drives 606Do not display information about the drives indicated. 607Multiple drives may be specified, separated by spaces. 608.It Cm drives Op Ar drives 609With no arguments, display a list of available drives. 610With arguments, replace the list of currently displayed drives 611with the ones specified. 612.El 613.Pp 614The following commands are specific to the 615.Ic inet.* , 616.Ic inet6.* , 617.Ic syscall 618and 619.Ic vmstat 620displays; the minimum unambiguous prefix may be supplied. 621.Pp 622.Bl -tag -width Ar -compact 623.It Cm boot 624Display cumulative statistics since the system was booted. 625.It Cm run 626Display statistics as a running total from the point this 627command is given. 628.It Cm time 629Display statistics averaged over the refresh interval (the default). 630.It Cm zero 631Reset running statistics to zero. 632.El 633.Sh FILES 634.Bl -tag -width /etc/networks -compact 635.It Pa /netbsd 636For the namelist. 637.It Pa /dev/kmem 638For information in main memory. 639.It Pa /etc/hosts 640For host names. 641.It Pa /etc/networks 642For network names. 643.It Pa /etc/services 644For port names. 645.El 646.Sh NOTES 647Much of the information that 648.Nm 649.Ic vmstat 650uses is obtained from 651.Cm struct vmmeter cnt . 652.Sh SEE ALSO 653.Xr df 1 , 654.Xr netstat 1 , 655.Xr ps 1 , 656.Xr top 1 , 657.Xr vmstat 1 , 658.Xr iostat 8 , 659.Xr pstat 8 660.Sh HISTORY 661The 662.Nm 663program appeared in 664.Bx 4.3 . 665.Sh BUGS 666Consumes CPU resources and thus may skew statistics. 667.Pp 668Certain displays presume a minimum of 80 characters per line. 669.Pp 670The 671.Ic vmstat 672display looks out of place because it is (it was added in as 673a separate display from what used to be a different program). 674.Pp 675The 676.Fl b 677option requires a real terminal and could be converted to 678simply output to standard output. 679