usr.bin/systat/systat.1

   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: src/usr.bin/systat/systat.1,v 1.23.2.9 2002/12/29 16:35:40 schweikh Exp $
  30 .\" $DragonFly: src/usr.bin/systat/systat.1,v 1.8 2008/09/02 11:50:46 matthias Exp $
  31 .\"
  32 .Dd September 28, 2009
  33 .Dt SYSTAT 1
  34 .Os
  35 .Sh NAME
  36 .Nm systat
  37 .Nd display system statistics on a crt
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl Ar display
  41 .Op Ar refresh-interval
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 utility displays various system statistics in a screen oriented fashion
  46 using the curses screen display library,
  47 .Xr ncurses 3 .
  48 .Pp
  49 While
  50 .Nm
  51 is running the screen is usually divided into two windows (an exception
  52 is the vmstat and pvmmeter displays which uses the entire screen).
  53 The upper window depicts the current system load average.
  54 The information displayed in the lower window may vary, depending on
  55 user commands.
  56 The last line on the screen is reserved for user input and error messages.
  57 .Pp
  58 By default
  59 .Nm
  60 displays the processes getting the largest percentage of the processor
  61 in the lower window.
  62 Other displays show swap space usage, disk
  63 .Tn I/O
  64 statistics (a la
  65 .Xr iostat 8 ) ,
  66 virtual memory statistics (a la
  67 .Xr vmstat 8 ) ,
  68 network ``mbuf'' utilization,
  69 .Tn TCP/IP
  70 statistics,
  71 and network connections (a la
  72 .Xr netstat 1 ) .
  73 .Pp
  74 Input is interpreted at two different levels.
  75 A ``global'' command interpreter processes all keyboard input.
  76 If this command interpreter fails to recognize a command, the
  77 input line is passed to a per-display command interpreter.
  78 This allows each display to have certain display-specific commands.
  79 .Pp
  80 Command line options:
  81 .Bl -tag -width "refresh_interval"
  82 .It Fl Ns Ar display
  83 The
  84 .Fl
  85 flag expects
  86 .Ar display
  87 to be one of:
  88 .Ic icmp ,
  89 .Ic icmp6 ,
  90 .Ic ifstat ,
  91 .Ic iostat ,
  92 .Ic ip ,
  93 .Ic ip6 ,
  94 .Ic mbufs ,
  95 .Ic netstat ,
  96 .Ic pigs ,
  97 .Ic pvmmeter ,
  98 .Ic sensors ,
  99 .Ic swap ,
 100 .Ic tcp ,
 101 or
 102 .Ic vmstat .
 103 These displays can also be requested interactively (without the
 104 .Dq Fl )
 105 and are described in
 106 full detail below.
 107 .It Ar refresh-interval
 108 The
 109 .Ar refresh-value
 110 specifies the screen refresh time interval in seconds.
 111 .El
 112 .Pp
 113 Certain characters cause immediate action by
 114 .Nm .
 115 These are
 116 .Bl -tag -width Fl
 117 .It Ic \&^L
 118 Refresh the screen.
 119 .It Ic \&^G
 120 Print the name of the current ``display'' being shown in
 121 the lower window and the refresh interval.
 122 .It Ic \&:
 123 Move the cursor to the command line and interpret the input
 124 line typed as a command.
 125 While entering a command the current character erase, word erase,
 126 and line kill characters may be used.
 127 .El
 128 .Pp
 129 The following commands are interpreted by the ``global'' command interpreter.
 130 .Bl -tag -width Fl
 131 .It Ic help
 132 Print the names of the available displays on the command line.
 133 .It Ic load
 134 Print the load average over the past 1, 5, and 15 minutes on the command line.
 135 .It Ic stop
 136 Stop refreshing the screen.
 137 .It Oo Ic start Oc Op Ar number
 138 Start (continue) refreshing the screen.
 139 If a second, numeric, argument is provided it is interpreted as a
 140 refresh interval (in seconds).
 141 Supplying only a number will set the refresh interval to this value.
 142 .It Ic quit
 143 Exit
 144 .Nm .
 145 (This may be abbreviated to
 146 .Ic q  . )
 147 .El
 148 .Pp
 149 The available displays are:
 150 .Bl -tag -width Ic
 151 .It Ic pigs
 152 Display, in the lower window, those processes resident in main
 153 memory and getting the
 154 largest portion of the processor (the default display).
 155 When less than 100% of the
 156 processor is scheduled to user processes, the remaining time
 157 is accounted to the ``idle'' process.
 158 .It Ic icmp
 159 Display, in the lower window, statistics about messages received and
 160 transmitted by the Internet Control Message Protocol
 161 .Pq Dq Tn ICMP .
 162 The left half of the screen displays information about received packets,
 163 and the right half displays information regarding transmitted packets.
 164 .Pp
 165 The
 166 .Ic icmp
 167 display understands two commands:
 168 .Ic mode
 169 and
 170 .Ic reset .
 171 The
 172 .Ic mode
 173 command is used to select one of four display modes, given as its argument:
 174 .Pp
 175 .Bl -tag -width absoluteXX -compact
 176 .It Ic rate
 177 Show the rate of change of each value in packets per second (the default).
 178 .It Ic delta
 179 Show the rate of change of each value in packets per refresh interval.
 180 .It Ic since
 181 Show the total change of each value since the display was last reset.
 182 .It Ic absolute
 183 Show the absolute value of each statistic.
 184 .El
 185 .Pp
 186 The
 187 .Ic reset
 188 command resets the baseline for
 189 .Ic since
 190 mode.
 191 The
 192 .Ic mode
 193 command with no argument will display the current mode in the command line.
 194 .It Ic icmp6
 195 This display is like the
 196 .Ic icmp
 197 display, but displays statistics for
 198 .Tn IPv6 ICMP .
 199 .It Ic ip
 200 Otherwise identical to the
 201 .Ic icmp
 202 display, except that it displays
 203 .Tn IP
 204 and
 205 .Tn UDP
 206 statistics.
 207 .It Ic ip6
 208 Like the
 209 .Ic ip
 210 display,
 211 except that it displays
 212 .Tn IPv6
 213 statistics.
 214 .It Ic tcp
 215 Like
 216 .Ic icmp ,
 217 but with
 218 .Tn TCP
 219 statistics.
 220 .It Ic ifstat
 221 Display, in the lower window, statistics about network throughput on
 222 a per-interface basis.
 223 .It Ic iostat
 224 Display, in the lower window, statistics about processor use
 225 and disk throughput.
 226 Statistics on processor use appear as
 227 bar graphs of the amount of time executing in user mode (`user'),
 228 in user mode running low priority processes (`nice'), in
 229 system mode (`system'), in interrupt mode (`interrupt'),
 230 and idle (`idle').
 231 Statistics on disk throughput show, for each drive, megabytes per second,
 232 average number of disk transactions per second, and
 233 average kilobytes of data per transaction.
 234 This information may be
 235 displayed as bar graphs or as rows of numbers which scroll downward.
 236 Bar graphs are shown by default.
 237 .Pp
 238 The following commands are specific to the
 239 .Ic iostat
 240 display; the minimum unambiguous prefix may be supplied.
 241 .Pp
 242 .Bl -tag -width Fl -compact
 243 .It Ic numbers
 244 Show the disk
 245 .Tn I/O
 246 statistics in numeric form.
 247 Values are displayed in numeric columns which scroll downward.
 248 .It Ic bars
 249 Show the disk
 250 .Tn I/O
 251 statistics in bar graph form (default).
 252 .It Ic kbpt
 253 Toggle the display of kilobytes per transaction.
 254 (the default is to not display kilobytes per transaction).
 255 .El
 256 .It Ic sensors
 257 Display, in the lower window,
 258 the current values of available hardware sensors,
 259 in a format similar to that of
 260 .Xr sysctl 8 .
 261 .It Ic swap
 262 Show information about swap space usage on all the
 263 swap areas compiled into the kernel.
 264 The first column is the device name of the partition.
 265 The next column is the total space available in the partition.
 266 The ``Used'' column indicates the total blocks used so far;
 267 the graph shows the percentage of space in use on each partition.
 268 If there are more than one swap partition in use,
 269 a total line is also shown.
 270 Areas known to the kernel, but not in use are shown as not available.
 271 .It Ic mbufs
 272 Display, in the lower window, the number of mbufs allocated
 273 for particular uses, i.e.\& data, socket structures, etc.
 274 .It Ic vmstat
 275 Take over the entire display and show a (rather crowded) compendium
 276 of statistics related to virtual memory usage, process scheduling,
 277 device interrupts, system name translation cacheing, disk
 278 .Tn I/O
 279 etc.
 280 .Pp
 281 The upper left quadrant of the screen shows the number
 282 of users logged in and the load average over the last one, five,
 283 and fifteen minute intervals.
 284 .Pp
 285 Below this line are statistics on memory utilization.
 286 The first row (`Act') reports memory usage only among active processes,
 287 that is processes that have run in the previous twenty seconds.
 288 The second row (`All') reports on memory usage of all processes.
 289 Two groups of columns are shown, `REAL' and `VIRTUAL'.
 290 The first column (`Tot') reports on the number of
 291 physical pages claimed by processes.
 292 The second column (`Share') reports the number of
 293 physical pages that are devoted to read only text pages.
 294 The third and fourth columns report the same two figures for
 295 virtual pages, that is the number of pages that would be
 296 needed if all processes had all of their pages.
 297 Finally the last column (`Free') shows the number of
 298 physical pages on the free list.
 299 .Pp
 300 Below the memory display is a list of the
 301 average number of processes (over the last refresh interval)
 302 that are runnable (`r'), in page wait (`p'),
 303 in disk wait other than paging (`d'),
 304 sleeping (`s'), and swapped out but desiring to run (`w').
 305 The row also shows the average number of context switches (`Csw'),
 306 traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'),
 307 network software interrupts (`Sof'), and page faults (`Flt').
 308 .Pp
 309 Below the process queue length listing is a listing of
 310 .Tn CPU
 311 usage, a numerical listing and a bar graph showing the amount of
 312 system (`='), interrupt (`+'), user (`>'), nice (`-'), and idle time (` ').
 313 .Pp
 314 Below the
 315 .Tn CPU
 316 usage display are statistics on name translations.
 317 It lists the number of path names translated
 318 in the previous interval (`Path-lookups'),
 319 the number and percentage of the path lookups that were
 320 handled by the name translation cache, and
 321 the average number of path components in path lookups (`Components').
 322 .Pp
 323 At the bottom left is the disk usage display.
 324 It reports the number of
 325 kilobytes per transaction (`KB/t'),
 326 read transactions per second (`tpr/s'),
 327 megabytes per second in read transaction (`MBr/s'),
 328 write transactions per second (`tpw/s'),
 329 megabytes per second in write transaction (`MBw/s') and
 330 the percentage of the time the disk was busy (`% busy') averaged
 331 over the refresh period of the display (by default, five seconds).
 332 The system keeps statistics on most every storage device.
 333 In general, up to seven devices are displayed.
 334 The devices displayed by default are the
 335 first devices in the kernel's device list.
 336 See
 337 .Xr devstat 3
 338 and
 339 .Xr devstat 9
 340 for details on the devstat system.
 341 .Pp
 342 If at most 4 disk devices are shown,
 343 extended virtual memory statistics are shown right to disk usage:
 344 pages zero filled on demand (`zfod'),
 345 pages optimized zero filled on demand (`ozfod'),
 346 slow (i.e.\& non-optimized) zero fills percentage (`%sloz'),
 347 total pages freed (`tfree').
 348 .Pp
 349 Under the date in the upper right hand quadrant are statistics
 350 on paging and swapping activity.
 351 The first two columns (`VN PAGER') report the average number of pages
 352 brought in and out per second over the last refresh interval
 353 due to page faults and the paging daemon.
 354 The third and fourth columns (`SWAP PAGER') report the average number of pages
 355 brought in and out per second over the last refresh interval
 356 due to swap requests initiated by the scheduler.
 357 The first row (`count') of the display shows the average
 358 number of disk transfers per second over the last refresh interval;
 359 the second row (`pages') of the display shows the average
 360 number of pages transferred per second over the last refresh interval.
 361 .Pp
 362 Below the paging statistics is a column of lines regarding the virtual
 363 memory system which list the average number of
 364 pages zero filled on demand (`zfod')
 365 (shown with extended virtual memory statistics if screen space permits),
 366 pages copied on write (`cow'),
 367 pages wired down (`wire'),
 368 active pages (`act'),
 369 inactive pages (`inact'),
 370 pages on the buffer cache queue (`cache'),
 371 number of free pages (`free'),
 372 pages freed by the page daemon (`daefr'),
 373 pages freed by exiting processes (`prcfr'),
 374 pages reactivated from the free list (`react'),
 375 times the page daemon was awakened (`pdwak'),
 376 pages analyzed by the page daemon (`pdpgs'),
 377 and
 378 intransit blocking page faults (`intrn')
 379 per second over the refresh interval.
 380 .Pp
 381 At the bottom of this column are lines showing the
 382 amount of memory, in kilobytes, used for the buffer cache (`buf'),
 383 the number of dirty buffers in the buffer cache (`dirtybuf'),
 384 desired maximum size of vnode cache (`desiredvnodes')
 385 (mostly unused, except to size the name cache),
 386 number of vnodes actually allocated (`numvnodes'),
 387 and
 388 number of allocated vnodes that are free (`freevnodes').
 389 .Pp
 390 Running down the right hand side of the display is a breakdown
 391 of the interrupts being handled by the system (`Interrupts').
 392 At the top of the list is the total interrupts per second
 393 over the time interval (`total').
 394 The rest of the column breaks down the total on a device by device basis.
 395 Only devices that have interrupted at least once since boot time are shown.
 396 .Pp
 397 The following commands are specific to the
 398 .Ic vmstat
 399 display; the minimum unambiguous prefix may be supplied.
 400 .Pp
 401 .Bl -tag -width Ar -compact
 402 .It Ic boot
 403 Display cumulative statistics since the system was booted.
 404 .It Ic run
 405 Display statistics as a running total from the point this command is given.
 406 .It Ic time
 407 Display statistics averaged over the refresh interval (the default).
 408 .It Ic want_fd
 409 Toggle the display of fd devices in the disk usage display.
 410 .It Ic zero
 411 Reset running statistics to zero.
 412 .El
 413 .It Ic pvmmeter
 414 Display per
 415 .Tn CPU
 416 statistics, including
 417 .Tn LAPIC
 418 timer interrupts (`timer'),
 419 .Tn IPIs
 420 (Inter-Processor Interrupts) (`ipi'),
 421 external interrupts (i.e.\& not timer or ipi) (`extint'), and
 422 .Tn CPU
 423 time breakdown (`user%', `nice%', `sys%', `intr%', and `idle%').
 424 .It Ic netstat
 425 Display, in the lower window, network connections.
 426 By default, network servers awaiting requests are not displayed.
 427 Each address is displayed in the format ``host.port'',
 428 with each shown symbolically, when possible.
 429 It is possible to have addresses displayed numerically,
 430 limit the display to a set of ports, hosts, and/or protocols
 431 (the minimum unambiguous prefix may be supplied):
 432 .Pp
 433 .Bl -tag -width Ar -compact
 434 .It Ic all
 435 Toggle the displaying of server processes awaiting requests (this
 436 is the equivalent of the
 437 .Fl a
 438 flag to
 439 .Xr netstat 1 ) .
 440 .It Ic numbers
 441 Display network addresses numerically.
 442 .It Ic names
 443 Display network addresses symbolically.
 444 .It Ic proto Ar protocol
 445 Display only network connections using the indicated
 446 .Ar protocol .
 447 Supported protocols are
 448 .Cm tcp ,
 449 .Cm udp ,
 450 and
 451 .Cm all .
 452 .It Ic ignore Op Ar items
 453 Do not display information about connections associated with
 454 the specified hosts or ports.
 455 Hosts and ports may be specified
 456 by name (``vangogh'', ``ftp''), or numerically.
 457 Host addresses use the Internet dot notation (``128.32.0.9'').
 458 Multiple items
 459 may be specified with a single command by separating them with spaces.
 460 .It Ic display Op Ar items
 461 Display information about the connections associated with the
 462 specified hosts or ports.
 463 As for
 464 .Ic ignore ,
 465 .Ar items
 466 may be names or numbers.
 467 .It Ic show Op Cm ports | hosts
 468 Show, on the command line, the currently selected protocols, hosts, and ports.
 469 Hosts and ports which are being ignored are prefixed with a `!'.
 470 If
 471 .Cm ports
 472 or
 473 .Cm hosts
 474 is supplied as an argument to
 475 .Ic show ,
 476 then only the requested information will be displayed.
 477 .It Ic reset
 478 Reset the port, host, and protocol matching mechanisms to the default
 479 (any protocol, port, or host).
 480 .El
 481 .El
 482 .Pp
 483 Commands to switch between displays may be abbreviated to the
 484 minimum unambiguous prefix; for example, ``io'' for ``iostat''.
 485 Certain information may be discarded when the screen size is
 486 insufficient for display.
 487 For example, on a machine with 10 drives the
 488 .Ic iostat
 489 bar graph displays only 3 drives on a 24 line terminal.
 490 When a bar graph would overflow the allotted screen space it is
 491 truncated and the actual value is printed ``over top'' of the bar.
 492 .Pp
 493 The following commands are common to each display which shows
 494 information about disk drives.
 495 These commands are used to
 496 select a set of drives to report on, should your system have
 497 more drives configured than can normally be displayed on the screen.
 498 .Pp
 499 .Bl -tag -width Ar -compact
 500 .It Ic ignore Op Ar drives
 501 Do not display information about the drives indicated.
 502 Multiple drives may be specified, separated by spaces.
 503 .It Ic display Op Ar drives
 504 Display information about the drives indicated.
 505 Multiple drives may be specified, separated by spaces.
 506 .It Ic only Op Ar drives
 507 Display only the specified drives.
 508 Multiple drives may be specified, separated by spaces.
 509 .It Ic drives
 510 Display a list of available devices.
 511 .It Ic match Ar type , Ns Ar if , Ns Ar pass Op | Ar ...
 512 Display devices matching the given pattern.
 513 The basic matching expressions are the same as those used in
 514 .Xr iostat 8
 515 with one difference.
 516 Instead of specifying multiple
 517 .Fl t
 518 arguments which are then ORed together, the user instead specifies multiple
 519 matching expressions joined by the pipe
 520 .Pq Ql \&|
 521 character.
 522 The comma separated arguments within each matching expression are ANDed
 523 together, and then the pipe separated matching expressions are ORed together.
 524 Any device matching the combined expression will be displayed,
 525 if there is room to display it.
 526 For example:
 527 .Pp
 528 .Dl match da,scsi | cd,ide
 529 .Pp
 530 This will display all
 531 .Tn SCSI
 532 Direct Access devices and all
 533 .Tn IDE CDROM
 534 devices.
 535 .Pp
 536 .Dl match da | sa | cd,pass
 537 .Pp
 538 This will display all Direct Access devices, all Sequential Access devices,
 539 and all passthrough devices that provide access to
 540 .Tn CDROM
 541 drives.
 542 .El
 543 .Sh FILES
 544 .Bl -tag -width /etc/networks -compact
 545 .It Pa /boot/kernel
 546 For the namelist.
 547 .It Pa /dev/kmem
 548 For information in main memory.
 549 .It Pa /etc/hosts
 550 For host names.
 551 .It Pa /etc/networks
 552 For network names.
 553 .It Pa /etc/services
 554 For port names.
 555 .El
 556 .Sh SEE ALSO
 557 .Xr netstat 1 ,
 558 .Xr kvm 3 ,
 559 .Xr icmp 4 ,
 560 .Xr icmp6 4 ,
 561 .Xr ip 4 ,
 562 .Xr ip6 4 ,
 563 .Xr tcp 4 ,
 564 .Xr udp 4 ,
 565 .Xr iostat 8 ,
 566 .Xr sysctl 8 ,
 567 .Xr vmstat 8
 568 .Sh HISTORY
 569 The
 570 .Nm
 571 program appeared in
 572 .Bx 4.3 .
 573 The
 574 .Ic icmp ,
 575 .Ic ip ,
 576 and
 577 .Ic tcp
 578 displays appeared in
 579 .Fx 3.0 ;
 580 the notion of having different display modes for the
 581 .Tn ICMP ,
 582 .Tn IP ,
 583 .Tn TCP ,
 584 and
 585 .Tn UDP
 586 statistics was stolen from the
 587 .Fl C
 588 option to
 589 .Xr netstat 1
 590 in Silicon Graphics'
 591 .Tn IRIX
 592 system.
 593 .Sh BUGS
 594 Certain displays presume a minimum of 80 characters per line.
 595 The
 596 .Ic vmstat
 597 display looks out of place because it is (it was added in as
 598 a separate display rather than created as a new program).