1.\" Copyright (c) 1985, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)systat.1 8.2 (Berkeley) 12/30/93 29.\" $FreeBSD$ 30.\" 31.Dd December 5, 2016 32.Dt SYSTAT 1 33.Os 34.Sh NAME 35.Nm systat 36.Nd display system statistics 37.Sh SYNOPSIS 38.Nm 39.Op Fl display 40.Op Ar display-commands 41.Op Ar refresh-interval 42.Sh DESCRIPTION 43The 44.Nm 45utility displays various system statistics in a screen oriented fashion 46using the curses screen display library, 47.Xr ncurses 3 . 48.Pp 49While 50.Nm 51is running the screen is usually divided into two windows (an exception 52is the vmstat display which uses the entire screen). 53The 54upper window depicts the current system load average. 55The 56information displayed in the lower window may vary, depending on 57user commands. 58The last line on the screen is reserved for user 59input and error messages. 60.Pp 61By default 62.Nm 63displays the processes getting the largest percentage of the processor 64in the lower window. 65Other displays show swap space usage, disk 66.Tn I/O 67statistics (a la 68.Xr iostat 8 ) , 69virtual memory statistics (a la 70.Xr vmstat 8 ) , 71.Tn TCP/IP 72statistics, 73and network connections (a la 74.Xr netstat 1 ) . 75.Pp 76Input is interpreted at two different levels. 77A ``global'' command interpreter processes all keyboard input. 78If this command interpreter fails to recognize a command, the 79input line is passed to a per-display command interpreter. 80This 81allows each display to have certain display-specific commands. 82.Pp 83Command line options: 84.Bl -tag -width "refresh_interval" 85.It Fl Ns Ar display 86The 87.Fl 88flag expects 89.Ar display 90to be one of: 91.Ic icmp , 92.Ic icmp6 , 93.Ic ifstat , 94.Ic iostat , 95.Ic ip , 96.Ic ip6 , 97.Ic netstat , 98.Ic pigs , 99.Ic sctp , 100.Ic swap , 101.Ic tcp , 102.Ic vmstat , 103or 104.Ic zarc , 105These displays can also be requested interactively (without the 106.Dq Fl ) 107and are described in 108full detail below. 109.It Ar refresh-interval 110The 111.Ar refresh-value 112specifies the screen refresh time interval in seconds. 113Time interval can be fractional. 114.It Ar display-commands 115A list of commands specific to this display. 116These commands can also be entered interactively and are described for 117each display separately below. 118If the command requires arguments, they can be specified as separate 119command line arguments. 120A command line argument 121.Fl - 122will finish display commands. 123For example: 124.Pp 125.Dl Nm Fl ifstat Fl match Ar bge0,em1 Fl pps 126.Pp 127This will display statistics of packets per second for network interfaces 128named as bge0 and em1. 129.Pp 130.Dl Nm Fl iostat Fl numbers Fl - Ar 2.1 131.Pp 132This will display all IO statistics in a numeric format and the information 133will be refreshed each 2.1 seconds. 134.El 135.Pp 136Certain characters cause immediate action by 137.Nm . 138These are 139.Bl -tag -width Fl 140.It Ic \&^L 141Refresh the screen. 142.It Ic \&^G 143Print the name of the current ``display'' being shown in 144the lower window and the refresh interval. 145.It Ic \&: 146Move the cursor to the command line and interpret the input 147line typed as a command. 148While entering a command the 149current character erase, word erase, and line kill characters 150may be used. 151.El 152.Pp 153The following commands are interpreted by the ``global'' 154command interpreter. 155.Bl -tag -width Fl 156.It Ic help 157Print the names of the available displays on the command line. 158.It Ic load 159Print the load average over the past 1, 5, and 15 minutes 160on the command line. 161.It Ic stop 162Stop refreshing the screen. 163.It Xo 164.Op Ic start 165.Op Ar number 166.Xc 167Start (continue) refreshing the screen. 168If a second, numeric, 169argument is provided it is interpreted as a refresh interval 170(in seconds). 171Supplying only a number will set the refresh interval to this 172value. 173.It Ic quit 174Exit 175.Nm . 176(This may be abbreviated to 177.Ic q . ) 178.El 179.Pp 180The available displays are: 181.Bl -tag -width Ic 182.It Ic pigs 183Display, in the lower window, those processes resident in main 184memory and getting the 185largest portion of the processor (the default display). 186When less than 100% of the 187processor is scheduled to user processes, the remaining time 188is accounted to the ``idle'' process. 189.It Ic icmp 190Display, in the lower window, statistics about messages received and 191transmitted by the Internet Control Message Protocol 192.Pq Dq Tn ICMP . 193The left half of the screen displays information about received 194packets, and the right half displays information regarding transmitted 195packets. 196.Pp 197The 198.Ic icmp 199display understands two commands: 200.Ic mode 201and 202.Ic reset . 203The 204.Ic mode 205command is used to select one of four display modes, given as its argument: 206.Bl -tag -width absoluteXX -compact 207.It Ic rate : 208show the rate of change of each value in packets (the default) 209per second 210.It Ic delta : 211show the rate of change of each value in packets per refresh interval 212.It Ic since : 213show the total change of each value since the display was last reset 214.It Ic absolute : 215show the absolute value of each statistic 216.El 217.Pp 218The 219.Ic reset 220command resets the baseline for 221.Ic since 222mode. 223The 224.Ic mode 225command with no argument will display the current mode in the command 226line. 227.It Ic icmp6 228This display is like the 229.Ic icmp 230display, 231but displays statistics for IPv6 ICMP. 232.It Ic ip 233Otherwise identical to the 234.Ic icmp 235display, except that it displays 236.Tn IP 237and 238.Tn UDP 239statistics. 240.It Ic ip6 241Like the 242.Ic ip 243display, 244except that it displays 245.Tn IPv6 246statistics. 247It does not display 248.Tn UDP statistics. 249.It Ic sctp 250Like 251.Ic icmp , 252but with 253.Tn SCTP 254statistics. 255.It Ic tcp 256Like 257.Ic icmp , 258but with 259.Tn TCP 260statistics. 261.It Ic iostat 262Display, in the lower window, statistics about processor use 263and disk throughput. 264Statistics on processor use appear as 265bar graphs of the amount of time executing in user mode (``user''), 266in user mode running low priority processes (``nice''), in 267system mode (``system''), in interrupt mode (``interrupt''), 268and idle (``idle''). 269Statistics 270on disk throughput show, for each drive, megabytes per second, 271average number of disk transactions per second, and 272average kilobytes of data per transaction. 273This information may be 274displayed as bar graphs or as rows of numbers which scroll downward. 275Bar 276graphs are shown by default. 277.Pp 278The following commands are specific to the 279.Ic iostat 280display; the minimum unambiguous prefix may be supplied. 281.Pp 282.Bl -tag -width Fl -compact 283.It Cm numbers 284Show the disk 285.Tn I/O 286statistics in numeric form. 287Values are 288displayed in numeric columns which scroll downward. 289.It Cm bars 290Show the disk 291.Tn I/O 292statistics in bar graph form (default). 293.It Cm kbpt 294Toggle the display of kilobytes per transaction. 295(the default is to 296not display kilobytes per transaction). 297.El 298.It Ic swap 299Show information about swap space usage on all the 300swap areas compiled into the kernel. 301The first column is the device name of the partition. 302The next column is the total space available in the partition. 303The 304.Ar Used 305column indicates the total blocks used so far; 306the graph shows the percentage of space in use on each partition. 307If there are more than one swap partition in use, 308a total line is also shown. 309Areas known to the kernel, but not in use are shown as not available. 310.It Ic vmstat 311Take over the entire display and show a (rather crowded) compendium 312of statistics related to virtual memory usage, process scheduling, 313device interrupts, system name translation caching, disk 314.Tn I/O 315etc. 316.Pp 317The upper left quadrant of the screen shows the number 318of users logged in and the load average over the last one, five, 319and fifteen minute intervals. 320Below this line are statistics on memory utilization. 321The first row of the table reports memory usage only among 322active processes, that is processes that have run in the previous 323twenty seconds. 324The second row reports on memory usage of all processes. 325The first column reports on the number of kilobytes in physical pages 326claimed by processes. 327The second column reports the number of kilobytes in physical pages that 328are devoted to read only text pages. 329The third and fourth columns report the same two figures for 330virtual pages, that is the number of kilobytes in pages that would be 331needed if all processes had all of their pages. 332Finally the last column shows the number of kilobytes in physical pages 333on the free list. 334.Pp 335Below the memory display is a list of the 336average number of processes (over the last refresh interval) 337that are runnable (`r'), in page wait (`p'), 338in disk wait other than paging (`d'), 339sleeping (`s'), and swapped out but desiring to run (`w'). 340The row also shows the average number of context switches 341(`Csw'), traps (`Trp'; includes page faults), system calls (`Sys'), 342interrupts (`Int'), network software interrupts (`Sof'), and page 343faults (`Flt'). 344.Pp 345Below the process queue length listing is a numerical listing and 346a bar graph showing the amount of 347system (shown as `='), interrupt (shown as `+'), user (shown as `>'), 348nice (shown as `-'), and idle time (shown as ` '). 349.Pp 350Below the process display are statistics on name translations. 351It lists the number of names translated in the previous interval, 352the number and percentage of the translations that were 353handled by the system wide name translation cache, and 354the number and percentage of the translations that were 355handled by the per process name translation cache. 356.Pp 357To the right of the name translations display are lines showing 358the number of dirty buffers in the buffer cache (`dtbuf'), 359desired maximum size of vnode cache (`desvn'), 360number of vnodes actually allocated (`numvn'), 361and 362number of allocated vnodes that are free (`frevn'). 363.Pp 364At the bottom left is the disk usage display. 365It reports the number of 366kilobytes per transaction, transactions per second, megabytes 367per second and the percentage of the time the disk was busy averaged 368over the refresh period of the display (by default, five seconds). 369The system keeps statistics on most every storage device. 370In general, up 371to seven devices are displayed. 372The devices displayed by default are the 373first devices in the kernel's device list. 374See 375.Xr devstat 3 376and 377.Xr devstat 9 378for details on the devstat system. 379.Pp 380Under the date in the upper right hand quadrant are statistics 381on paging and swapping activity. 382The first two columns report the average number of pages 383brought in and out per second over the last refresh interval 384due to page faults and the paging daemon. 385The third and fourth columns report the average number of pages 386brought in and out per second over the last refresh interval 387due to swap requests initiated by the scheduler. 388The first row of the display shows the average 389number of disk transfers per second over the last refresh interval; 390the second row of the display shows the average 391number of pages transferred per second over the last refresh interval. 392.Pp 393Below the paging statistics is a column of lines regarding the virtual 394memory system. 395The first few lines describe, 396in units (except as noted below) 397of pages per second averaged over the sampling interval, 398pages copied on write (`cow'), 399pages zero filled on demand (`zfod'), 400pages optimally zero filled on demand (`ozfod'), 401the ratio of the (average) ozfod / zfod as a percentage (`%ozfod'), 402pages freed by the page daemon (`daefr'), 403pages freed by exiting processes (`prcfr'), 404total pages freed (`totfr'), 405pages reactivated from the free list (`react'), 406the average number of 407times per second that the page daemon was awakened (`pdwak'), 408pages analyzed by the page daemon (`pdpgs'), 409and 410in-transit blocking page faults (`intrn'). 411Note that the units are special for `%ozfod' and `pdwak'. 412The next few lines describe, 413as amounts of memory in kilobytes, 414pages wired down (`wire'), 415active pages (`act'), 416inactive pages (`inact'), 417dirty pages queued for laundering (`laund'), 418and 419free pages (`free'). 420Note that the values displayed are the current transient ones; 421they are not averages. 422.Pp 423At the bottom of this column is a line showing the 424amount of virtual memory, in kilobytes, mapped into the buffer cache (`buf'). 425This statistic is not useful. 426It exists only as a placeholder for the corresponding useful statistic 427(the amount of real memory used to cache disks). 428The most important component of the latter (the amount of real memory 429used by the vm system to cache disks) is not available, 430but can be guessed from the `inact' amount under some system loads. 431.Pp 432Running down the right hand side of the display is a breakdown 433of the interrupts being handled by the system. 434At the top of the list is the total interrupts per second 435over the time interval. 436The rest of the column breaks down the total on a device 437by device basis. 438Only devices that have interrupted at least once since boot time are shown. 439.Pp 440The following commands are specific to the 441.Ic vmstat 442display; the minimum unambiguous prefix may be supplied. 443.Pp 444.Bl -tag -width Ar -compact 445.It Cm boot 446Display cumulative statistics since the system was booted. 447.It Cm run 448Display statistics as a running total from the point this 449command is given. 450.It Cm time 451Display statistics averaged over the refresh interval (the default). 452.It Cm zero 453Reset running statistics to zero. 454.El 455.It Ic zarc 456display arc cache usage and hit/miss statistics. 457.It Ic netstat 458Display, in the lower window, network connections. 459By default, 460network servers awaiting requests are not displayed. 461Each address 462is displayed in the format ``host.port'', with each shown symbolically, 463when possible. 464It is possible to have addresses displayed numerically, 465limit the display to a set of ports, hosts, and/or protocols 466(the minimum unambiguous prefix may be supplied): 467.Pp 468.Bl -tag -width Ar -compact 469.It Cm all 470Toggle the displaying of server processes awaiting requests (this 471is the equivalent of the 472.Fl a 473flag to 474.Xr netstat 1 ) . 475.It Cm numbers 476Display network addresses numerically. 477.It Cm names 478Display network addresses symbolically. 479.It Cm proto Ar protocol 480Display only network connections using the indicated 481.Ar protocol . 482Supported protocols are ``tcp'', ``udp'', and ``all''. 483.It Cm ignore Op Ar items 484Do not display information about connections associated with 485the specified hosts or ports. 486Hosts and ports may be specified 487by name (``vangogh'', ``ftp''), or numerically. 488Host addresses 489use the Internet dot notation (``128.32.0.9''). 490Multiple items 491may be specified with a single command by separating them with 492spaces. 493.It Cm display Op Ar items 494Display information about the connections associated with the 495specified hosts or ports. 496As for 497.Ar ignore , 498.Op Ar items 499may be names or numbers. 500.It Cm show Op Ar ports\&|hosts 501Show, on the command line, the currently selected protocols, 502hosts, and ports. 503Hosts and ports which are being ignored 504are prefixed with a `!'. 505If 506.Ar ports 507or 508.Ar hosts 509is supplied as an argument to 510.Cm show , 511then only the requested information will be displayed. 512.It Cm reset 513Reset the port, host, and protocol matching mechanisms to the default 514(any protocol, port, or host). 515.El 516.It Ic ifstat 517Display the network traffic going through active interfaces on the 518system. 519Idle interfaces will not be displayed until they receive some 520traffic. 521.Pp 522For each interface being displayed, the current, peak and total 523statistics are displayed for incoming and outgoing traffic. 524By default, 525the 526.Ic ifstat 527display will automatically scale the units being used so that they are 528in a human-readable format. 529The scaling units used for the current and 530peak 531traffic columns can be altered by the 532.Ic scale 533command. 534.Bl -tag -width ".Cm scale Op Ar units" 535.It Cm scale Op Ar units 536Modify the scale used to display the current and peak traffic over all 537interfaces. 538The following units are recognised: kbit, kbyte, mbit, 539mbyte, gbit, gbyte and auto. 540.It Cm pps 541Show statistics in packets per second instead of bytes/bits per second. 542A subsequent call of 543.Ic pps 544switches this mode off. 545.It Cm match Op Ar patterns 546Display only interfaces that match pattern provided as an argument. 547Patterns should be in shell syntax separated by whitespaces or commas. 548If this command is called without arguments then all interfaces are displayed. 549For example: 550.Pp 551.Dl match em0, bge1 552.Pp 553This will display em0 and bge1 interfaces. 554.Pp 555.Dl match em*, bge*, lo0 556.Pp 557This will display all 558.Ic em 559interfaces, all 560.Ic bge 561interfaces and the loopback interface. 562.El 563.El 564.Pp 565Commands to switch between displays may be abbreviated to the 566minimum unambiguous prefix; for example, ``io'' for ``iostat''. 567Certain information may be discarded when the screen size is 568insufficient for display. 569For example, on a machine with 10 570drives the 571.Ic iostat 572bar graph displays only 3 drives on a 24 line terminal. 573When 574a bar graph would overflow the allotted screen space it is 575truncated and the actual value is printed ``over top'' of the bar. 576.Pp 577The following commands are common to each display which shows 578information about disk drives. 579These commands are used to 580select a set of drives to report on, should your system have 581more drives configured than can normally be displayed on the 582screen. 583.Pp 584.Bl -tag -width Ar -compact 585.It Cm ignore Op Ar drives 586Do not display information about the drives indicated. 587Multiple 588drives may be specified, separated by spaces. 589.It Cm display Op Ar drives 590Display information about the drives indicated. 591Multiple drives 592may be specified, separated by spaces. 593.It Cm only Op Ar drives 594Display only the specified drives. 595Multiple drives may be specified, 596separated by spaces. 597.It Cm drives 598Display a list of available devices. 599.It Cm match Xo 600.Ar type , Ns Ar if , Ns Ar pass 601.Op | Ar ... 602.Xc 603Display devices matching the given pattern. 604The basic matching 605expressions are the same as those used in 606.Xr iostat 8 607with one difference. 608Instead of specifying multiple 609.Fl t 610arguments which are then ORed together, the user instead specifies multiple 611matching expressions joined by the pipe 612.Pq Ql \&| 613character. 614The comma 615separated arguments within each matching expression are ANDed together, and 616then the pipe separated matching expressions are ORed together. 617Any 618device matching the combined expression will be displayed, if there is room 619to display it. 620For example: 621.Pp 622.Dl match da,scsi | cd,ide 623.Pp 624This will display all SCSI Direct Access devices and all IDE CDROM devices. 625.Pp 626.Dl match da | sa | cd,pass 627.Pp 628This will display all Direct Access devices, all Sequential Access devices, 629and all passthrough devices that provide access to CDROM drives. 630.El 631.Sh FILES 632.Bl -tag -width /boot/kernel/kernel -compact 633.It Pa /boot/kernel/kernel 634For the namelist. 635.It Pa /dev/kmem 636For information in main memory. 637.It Pa /etc/hosts 638For host names. 639.It Pa /etc/networks 640For network names. 641.It Pa /etc/services 642For port names. 643.El 644.Sh SEE ALSO 645.Xr netstat 1 , 646.Xr kvm 3 , 647.Xr icmp 4 , 648.Xr icmp6 4 , 649.Xr ip 4 , 650.Xr ip6 4 , 651.Xr tcp 4 , 652.Xr udp 4 , 653.Xr gstat 8 , 654.Xr iostat 8 , 655.Xr vmstat 8 656.Sh HISTORY 657The 658.Nm 659program appeared in 660.Bx 4.3 . 661The 662.Ic icmp , 663.Ic ip , 664and 665.Ic tcp 666displays appeared in 667.Fx 3.0 ; 668the notion of having different display modes for the 669.Tn ICMP , 670.Tn IP , 671.Tn TCP , 672and 673.Tn UDP 674statistics was stolen from the 675.Fl C 676option to 677.Xr netstat 1 678in Silicon Graphics' 679.Tn IRIX 680system. 681.Sh BUGS 682Certain displays presume a minimum of 80 characters per line. 683The 684.Ic vmstat 685display looks out of place because it is (it was added in as 686a separate display rather than created as a new program). 687