1.\" $NetBSD: systat.1,v 1.52 2021/08/21 13:22:19 christos 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 August 21, 2021 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 bnz 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.It Fl z 145Display 0 instead of space when there is no data. 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.It Ic inet.icmp 280Display ICMP statistics. 281.It Ic inet.ip 282Display IPv4 and UDP statistics. 283.It Ic inet.tcp 284Display TCP statistics. 285.It Ic inet.tcpsyn 286Display statistics about the TCP ``syncache''. 287.It Ic inet6.ip6 288Display IPv6 statistics. 289.It Ic iostat 290Display, in the lower window, statistics about processor use 291and disk throughput. 292Statistics on processor use appear as bar graphs of the amount of 293time executing in user mode (``user''), in user mode running low 294priority processes (``nice''), in system mode (``system''), and 295idle (``idle''). 296Statistics on disk throughput show, for each drive, kilobytes of 297data transferred, number of disk transactions performed, and time 298spent in disk accesses in milliseconds. 299This information may be displayed as bar graphs or as rows of 300numbers which scroll downward. 301Bar graphs are shown by default; 302.Pp 303The following commands are specific to the 304.Ic iostat 305display; the minimum unambiguous prefix may be supplied. 306.Pp 307.Bl -tag -width Fl -compact 308.It Cm numbers 309Show the disk I/O statistics in numeric form. 310Values are 311displayed in numeric columns which scroll downward. 312.It Cm bars 313Show the disk I/O statistics in bar graph form (default). 314.It Cm secs 315Toggle the display of time in disk activity (the default is to 316not display time). 317.It Cm all 318Show the read and write statistics combined (default). 319.It Cm rw 320Show the read and write statistics separately. 321.El 322.It Ic mbufs 323Display, in the lower window, the number of mbufs allocated 324for particular uses, i.e. data, socket structures, etc. 325.It Ic netstat 326Display, in the lower window, network connections. 327By default, network servers awaiting requests are not displayed. 328Each address is displayed in the format ``host.port'', with each 329shown symbolically, when possible. 330It is possible to have addresses displayed numerically, 331limit the display to a set of ports, hosts, and/or protocols 332(the minimum unambiguous prefix may be supplied): 333.Pp 334.Bl -tag -width Ar -compact 335.It Cm all 336Toggle the displaying of server processes awaiting requests (this 337is the equivalent of the 338.Fl a 339flag to 340.Ar netstat 1 ) . 341.It Cm numbers 342Display network addresses numerically. 343.It Cm names 344Display network addresses symbolically. 345.It Ar protocol 346Display only network connections using the indicated protocol 347(currently either ``tcp'' or ``udp''). 348.It Cm ignore Op Ar items 349Do not display information about connections associated with 350the specified hosts or ports. 351Hosts and ports may be specified by name (``vangogh'', ``ftp''), 352or numerically. 353Host addresses use the Internet dot notation (``128.32.0.9''). 354Multiple items may be specified with a single command by separating 355them with spaces. 356.It Cm display Op Ar items 357Display information about the connections associated with the 358specified hosts or ports. 359As for 360.Ar ignore , 361.Op Ar items 362may be names or numbers. 363.It Cm show Op Ar ports\&|hosts 364Show, on the command line, the currently selected protocols, 365hosts, and ports. 366Hosts and ports which are being ignored are prefixed with a `!'. 367If 368.Ar ports 369or 370.Ar hosts 371is supplied as an argument to 372.Cm show , 373then only the requested information will be displayed. 374.It Cm reset 375Reset the port, host, and protocol matching mechanisms to the default 376(any protocol, port, or host). 377.El 378.It Ic pigs 379Display, in the lower window, those processes which are getting the 380largest portion of the processor (the default display). 381When less than 100% of the 382processor is scheduled to user processes, the remaining time 383is accounted to the ``idle'' process. 384.It Ic ps 385Display, in the lower window, the same information provided 386by the command 387.Xr ps 1 388with the flags 389.Fl aux . 390.Pp 391The following command is specific to the 392.Ic ps 393display; the minimum unambiguous prefix may be supplied. 394.Pp 395.Bl -tag -width Fl -compact 396.It Cm user Ar name 397Limit the list of processes displayed to those owned by user 398.Ar name . 399If 400.Ar name 401is specified as `+', processes owned by any user are displayed (default). 402.El 403.It Ic swap 404Show information about swap space usage on all the 405swap areas configured with 406.Xr swapctl 8 . 407The first column is the device name of the partition. 408The next column is the total space available in the partition. 409The 410.Ar Used 411column indicates the total blocks used so far; 412the graph shows the percentage of space in use on each partition. 413If there are more than one swap partition in use, 414a total line is also shown. 415Areas known to the kernel, but not in use are shown as not available. 416.It Ic syscall 417Show per system call statistics. 418The display consists of several columns of system call name and counts. 419.Pp 420In order to stop entries moving around the screen too much, an infinite 421response filter is applied to the values before they are sorted. 422.Pp 423The following commands are specific to the 424.Ic syscall 425display: 426.Pp 427.Bl -tag -width Ar -compact 428.It Ic sort Ic name 429Sort display by the syscall name (default). 430.It Ic sort Ic count 431Sort display by the count of calls or time spent in the calls. 432.It Ic sort Ic syscall 433Sort display be syscall number. 434.It Ic show Ic count 435Show the number of times the system call has be called (default). 436.It Ic show Ic time 437Show the average amount of time (in arbitrary units) spent in a call of 438the syscall. 439.El 440.It Ic vmstat 441Take over the entire display and show a (rather crowded) compendium 442of statistics related to virtual memory usage, process scheduling, 443device interrupts, system name translation caching, disk I/O etc. 444.Pp 445The upper left quadrant of the screen shows the number 446of users logged in and the load average over the last one, five, 447and fifteen minute intervals. 448Below this are statistics on memory utilization. 449The first row of the table reports memory usage only among 450active processes, that is processes that have run in the previous 451twenty seconds. 452The second row reports on memory usage of all processes. 453The first column reports on the number of physical pages 454claimed by processes. 455The second column reports the number of physical pages that 456are devoted to read only text pages. 457The third and fourth columns report the same two figures for 458virtual pages, that is the number of pages that would be 459needed if all processes had all of their pages. 460Finally the last column shows the number of physical pages 461on the free list. 462.Pp 463Below the memory display is a list of the 464average number of processes (over the last refresh interval) 465that are runnable (`r'), in page wait (`p'), 466in disk wait other than paging (`d'), sleeping (`s'). 467Below the queue length listing is a numerical listing and 468a bar graph showing the amount of 469system (shown as `='), user (shown as `>'), 470nice (shown as `-'), and idle time (shown as ` '). 471.Pp 472To the right of the process statistics is a column that 473lists the average number of context switches (`Csw'), 474traps (`Traps'; includes page faults), system calls (`SysCa'), interrupts (`Intr'), 475network software interrupts (`Soft'), 476page faults (`Fault'). 477.Pp 478Below this are statistics on memory utilization. 479The first row of the table reports memory usage only among 480active processes, that is processes that have run in the previous 481twenty seconds. 482The second row reports on memory usage of all processes. 483The first column reports on the number of physical pages 484claimed by processes. 485The second column reports the number of pages of memory and swap. 486The third column gives the number of pages of free memory and swap. 487.Pp 488Below the memory display are statistics on name translations. 489It lists the number of names translated in the previous interval, 490the number and percentage of the translations that were 491handled by the system wide name translation cache, and 492the number and percentage of the translations that were 493handled by the per process name translation cache. 494.Pp 495At the bottom left is the disk usage display. 496It reports the number of seeks, transfers, number 497of kilobyte blocks transferred per second averaged over the 498refresh period of the display (by default, five seconds), and 499the time spent in disk accesses. 500If there are more than five disks, and the terminal window has more 501than 24 lines, the disks display will be flipped so that more 502of the disk statistics are visible. 503.Pp 504Under the date in the upper right hand quadrant are statistics 505on paging and swapping activity. 506The first two columns report the average number of pages 507brought in and out per second over the last refresh interval 508due to page faults and the paging daemon. 509The third and fourth columns report the average number of pages 510brought in and out per second over the last refresh interval 511due to swap requests initiated by the scheduler. 512The first row of the display shows the average 513number of disk transfers per second over the last refresh interval; 514the second row of the display shows the average 515number of pages transferred per second over the last refresh interval. 516.Pp 517Below the paging statistics is another columns of paging data. 518From top to bottom, these represent: 519.Pp 520.Bl -tag -width Fl -compact 521.It Sq Ic forks 522number of 523.Fn fork 524calls 525.It Sq Ic fkppw 526number of 527.Fn fork 528calls where parent waits 529.It Sq Ic fksvm 530number of 531.Fn fork 532calls where vmspace is shared 533.It Sq Ic pwait 534number of times fault had to wait on a page 535.It Sq Ic relck 536number of times 537.Fn uvmfault_relock 538is called 539.It Sq Ic rlkok 540number of times 541.Fn uvmfault_relock 542is a success 543.It Sq Ic noram 544number of times fault was out of RAM 545.It Sq Ic ndcpy 546number of times fault clears ``needs copy'' 547.It Sq Ic fltcp 548number of times fault promotes with copy (2b) 549.It Sq Ic zfod 550number of times fault promotes with zerofill (2b) 551.It Sq Ic cow 552number of times faulted for anonymous for Copy-On-Write (case 1b) 553.It Sq Ic fmin 554min number of free pages 555.It Sq Ic ftarg 556target number of free pages 557.It Sq Ic itarg 558target number of inactive pages 559.It Sq Ic flnan 560number of times fault was out of anonymous pages 561.It Sq Ic pdfre 562number of pages daemon freed since boot 563.It Sq Ic pdscn 564number of pages daemon scanned since boot 565.El 566.Pp 567Note that the `%zfod' percentage is usually less than 100%, 568however it may exceed 100% if a large number of requests 569are actually used long after they were set up during a 570period when no new pages are being set up. 571Thus this figure is most interesting when observed over 572a long time period, such as from boot time 573(see below on getting such a display). 574.Pp 575To the left of the column of paging statistics is a breakdown 576of the interrupts being handled by the system. 577At the top of the list is the total interrupts per second 578over the time interval. 579The rest of the column breaks down the total on a device 580by device basis. 581Only devices that have interrupted at least once since boot time are shown. 582.El 583.Pp 584Commands to switch between displays may be abbreviated to the 585minimum unambiguous prefix; for example, ``io'' for ``iostat''. 586Certain information may be discarded when the screen size is 587insufficient for display. 588For example, on a machine with 10 drives the 589.Ic iostat 590bar graph displays only 3 drives on a 24 line terminal. 591When a bar graph would overflow the allotted screen space it is 592truncated and the actual value is printed ``over top'' of the bar. 593.Pp 594The following commands are common to each display which shows 595information about disk drives. 596These commands are used to select a set of drives to report on, 597should your system have more drives configured than can normally 598be displayed on the screen. 599Drives may be specified as drive names or as patterns specified in the 600notation described by 601.Xr fnmatch 3 . 602.Pp 603.Bl -tag -width Ar -compact 604.It Cm display Op Ar drives 605Display information about the drives indicated. 606Multiple drives may be specified, separated by spaces. 607.It Cm ignore Op Ar drives 608Do not display information about the drives indicated. 609Multiple drives may be specified, separated by spaces. 610.It Cm drives Op Ar drives 611With no arguments, display a list of available drives. 612With arguments, replace the list of currently displayed drives 613with the ones specified. 614.El 615.Pp 616The following commands are specific to the 617.Ic inet.* , 618.Ic inet6.* , 619.Ic syscall 620and 621.Ic vmstat 622displays; the minimum unambiguous prefix may be supplied. 623.Pp 624.Bl -tag -width Ar -compact 625.It Cm boot 626Display cumulative statistics since the system was booted. 627.It Cm run 628Display statistics as a running total from the point this 629command is given. 630.It Cm time 631Display statistics averaged over the refresh interval (the default). 632.It Cm zero 633Reset running statistics to zero. 634.El 635.Sh FILES 636.Bl -tag -width /etc/networks -compact 637.It Pa /netbsd 638For the namelist. 639.It Pa /dev/kmem 640For information in main memory. 641.It Pa /etc/hosts 642For host names. 643.It Pa /etc/networks 644For network names. 645.It Pa /etc/services 646For port names. 647.El 648.Sh NOTES 649Much of the information that 650.Nm 651.Ic vmstat 652uses is obtained from 653.Cm struct vmmeter cnt . 654.Sh SEE ALSO 655.Xr df 1 , 656.Xr netstat 1 , 657.Xr ps 1 , 658.Xr top 1 , 659.Xr vmstat 1 , 660.Xr iostat 8 , 661.Xr pstat 8 662.Sh HISTORY 663The 664.Nm 665program appeared in 666.Bx 4.3 . 667.Sh BUGS 668Consumes CPU resources and thus may skew statistics. 669.Pp 670Certain displays presume a minimum of 80 characters per line. 671.Pp 672The 673.Ic vmstat 674display looks out of place because it is (it was added in as 675a separate display from what used to be a different program). 676.Pp 677The 678.Fl b 679option requires a real terminal and could be converted to 680simply output to standard output. 681