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