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