1 KSTAT(1M)                    Maintenance Commands                    KSTAT(1M)
   2 
   3 NAME
   4      kstat - display kernel statistics
   5 
   6 SYNOPSIS
   7      kstat [-Cjlpq] [-T u|d] [-c class] [-m module] [-i instance] [-n name]
   8            [-s statistic] [-H o|b|u|d|n|I|Z] [interval [count]]
   9      kstat [-Cjlpq] [-T u|d] [-c class] [-H o|b|u|d|n|I|Z]
  10            [module[:instance[:name[:statistic]]]] ... [interval [count]]
  11 
  12 DESCRIPTION
  13      The kstat utility examines the available kernel statistics, or kstats, on
  14      the system and reports those statistics which match the criteria
  15      specified on the command line. Each matching statistic is printed with
  16      its module, instance, and name fields, as well as its actual value.
  17 
  18      Kernel statistics may be published by various kernel subsystems, such as
  19      drivers or loadable modules; each kstat has a module field that denotes
  20      its publisher. Since each module might have countable entities (such as
  21      multiple disks associated with the sd(7) driver) for which it wishes to
  22      report statistics, the kstat also has an instance field to index the
  23      statistics for each entity; kstat instances are numbered starting from
  24      zero. Finally, the kstat is given a name unique within its module.
  25 
  26      Each kstat may be a special kstat type, an array of name-value pairs, or
  27      raw data. In the name-value case, each reported value is given a label,
  28      which we refer to as the statistic. Known raw and special kstats are
  29      given statistic labels for each of their values by kstat; thus, all
  30      published values can be referenced as module:instance:name:statistic.
  31 
  32      When invoked without any module operands or options, kstat will match all
  33      defined statistics on the system. Example invocations are provided below.
  34 
  35 OPTIONS
  36      The tests specified by the following options are logically ANDed, and all
  37      matching kstats will be selected. A regular expression containing shell
  38      metacharacters must be protected from the shell by enclosing it with the
  39      appropriate quotes.
  40 
  41      The argument for the -c, -i, -m, -n, and -s options may be specified as a
  42      shell glob pattern, or a regular expression enclosed in '/' characters.
  43 
  44      -C      Displays output in parseable format with a colon as separator.
  45 
  46      -H o|b|u|d|n|I|Z
  47              Displays times in the specified format, after normalizing them.
  48              This can be any of the following:
  49 
  50              o       Displays snapshot and creation times as a fractional
  51                      number of seconds since boot, and other times as a whole
  52                      number of nanoseconds since boot.  This the default
  53                      behavior.
  54 
  55              b       Displays a fractional number of seconds since system
  56                      boot.
  57 
  58              u       Displays a fractional number of seconds since the epoch
  59                      (Jan 1, 1970 UTC).
  60 
  61              d       Displays in the same format as from date(1).
  62 
  63              n       Displays a whole number of nanoseconds since the epoch.
  64 
  65              I       Displays an ISO 8601:2000 standard time format in the
  66                      local timezone.
  67 
  68              Z       Displays an ISO 8601:2000 standard time format in UTC.
  69 
  70              Note that when using normalized time formats, the accuracy of the
  71              result will depend on the resolution of the realtime clock (see
  72              clock_gettime(3C) ), and in no case will be more accurate to
  73              absolute time than one microsecond.  However, any offset error
  74              between timestamps will be the same for all values displayed
  75              within a single kstat snapshot.
  76 
  77      -c class
  78              Displays only kstats that match the specified class.  class is a
  79              kernel-defined string which classifies the "type" of the kstat.
  80 
  81      -i instance
  82              Displays only kstats that match the specified instance.
  83 
  84      -j      Displays output in JSON format.
  85 
  86      -l      Lists matching kstat names without displaying values.
  87 
  88      -m module
  89              Displays only kstats that match the specified module.
  90 
  91      -n name
  92              Displays only kstats that match the specified name.
  93 
  94      -p      Displays output in parseable format. All example output in this
  95              document is given in this format. If this option is not
  96              specified, kstat produces output in a human-readable, table
  97              format.
  98 
  99      -q      Displays no output, but return appropriate exit status for
 100              matches against given criteria.
 101 
 102      -s statistic
 103              Displays only kstats that match the specified statistic.
 104 
 105      -T d|u  Displays a time stamp before each statistics block, either in
 106              date(1) format (d) or as an alphanumeric representation of the
 107              value returned by time(2) (u).
 108 
 109 OPERANDS
 110      The following operands are supported:
 111 
 112      module:instance:name:statistic
 113              Alternate method of specifying module, instance, name, and
 114              statistic as described above. Each of the module, instance, name,
 115              or statistic specifiers may be a shell glob pattern or a regular
 116              expression enclosed by '/' characters. It is possible to use both
 117              specifier types within a single operand.  Leaving a specifier
 118              empty is equivalent to using the '*' glob pattern for that
 119              specifier.
 120 
 121      interval
 122              The number of seconds between reports.
 123 
 124      count   The number of reports to be printed.
 125 
 126 FILES
 127      /dev/kstat
 128              kernel statistics driver
 129 
 130 EXIT STATUS
 131      The following exit values are returned:
 132 
 133      0       One or more statistics were matched.
 134      1       No statistics were matched.
 135      2       Invalid command line options were specified.
 136      3       A fatal error occurred.
 137 
 138 EXAMPLES
 139      In the following examples, all the command lines in a block produce the
 140      same output, as shown immediately below. The exact statistics and values
 141      will of course vary from machine to machine.
 142 
 143    Example 1: Using the kstat Command
 144            example$ lstat -p -m unix -i 0 -n system_misc -s 'avenrun*'
 145            example$ kstat -p -s 'avenrun*'
 146            example$ kstat -p 'unix:0:system_misc:avenrun*'
 147            example$ kstat -p ':::avenrun*'
 148            example$ kstat -p ':::/^avenrun_[0-9]+min$/'
 149 
 150            unix:0:system_misc:avenrun_15min        3
 151            unix:0:system_misc:avenrun_1min 4
 152            unix:0:system_misc:avenrun_5min 2
 153 
 154    Example 2: Using the kstat Command
 155            example$ kstat -p -m cpu_stat -s 'intr*'
 156            example$ kstat -p cpu_stat:::/^intr/
 157 
 158            cpu_stat:0:cpu_stat0:intr       29682330
 159            cpu_stat:0:cpu_stat0:intrblk    87
 160            cpu_stat:0:cpu_stat0:intrthread 15054222
 161            cpu_stat:1:cpu_stat1:intr       426073
 162            cpu_stat:1:cpu_stat1:intrblk    51
 163            cpu_stat:1:cpu_stat1:intrthread 289668
 164            cpu_stat:2:cpu_stat2:intr       134160
 165            cpu_stat:2:cpu_stat2:intrblk    0
 166            cpu_stat:2:cpu_stat2:intrthread 131
 167            cpu_stat:3:cpu_stat3:intr       196566
 168            cpu_stat:3:cpu_stat3:intrblk    30
 169            cpu_stat:3:cpu_stat3:intrthread 59626
 170 
 171    Example 3: Using the kstat Command
 172            example$ kstat -p :::state ':::avenrun*'
 173            example$ kstat -p :::state :::/^avenrun/
 174 
 175            cpu_info:0:cpu_info0:state      on-line
 176            cpu_info:1:cpu_info1:state      on-line
 177            cpu_info:2:cpu_info2:state      on-line
 178            cpu_info:3:cpu_info3:state      on-line
 179            unix:0:system_misc:avenrun_15min        4
 180            unix:0:system_misc:avenrun_1min 10
 181            unix:0:system_misc:avenrun_5min 3
 182 
 183    Example 4: Using the kstat Command
 184            example$ kstat -p 'unix:0:system_misc:avenrun*' 1 3
 185            unix:0:system_misc:avenrun_15min        15
 186            unix:0:system_misc:avenrun_1min 11
 187            unix:0:system_misc:avenrun_5min 21
 188 
 189            unix:0:system_misc:avenrun_15min        15
 190            unix:0:system_misc:avenrun_1min 11
 191            unix:0:system_misc:avenrun_5min 21
 192 
 193            unix:0:system_misc:avenrun_15min        15
 194            unix:0:system_misc:avenrun_1min 11
 195            unix:0:system_misc:avenrun_5min 21
 196 
 197    Example 5: Using the kstat Command
 198            example$ kstat -p -T d 'unix:0:system_misc:avenrun*' 5 2
 199            Thu Jul 22 19:39:50 1999
 200            unix:0:system_misc:avenrun_15min        12
 201            unix:0:system_misc:avenrun_1min 0
 202            unix:0:system_misc:avenrun_5min 11
 203 
 204            Thu Jul 22 19:39:55 1999
 205            unix:0:system_misc:avenrun_15min        12
 206            unix:0:system_misc:avenrun_1min 0
 207            unix:0:system_misc:avenrun_5min 11
 208 
 209    Example 6: Using the kstat Command
 210            example$ kstat -p -T u 'unix:0:system_misc:avenrun*'
 211            932668656
 212            unix:0:system_misc:avenrun_15min        14
 213            unix:0:system_misc:avenrun_1min 5
 214            unix:0:system_misc:avenrun_5min 18
 215 
 216 SEE ALSO
 217      date(1), sh(1), time(2), clock_gettime(3C), gmatch(3GEN), kstat(3KSTAT),
 218      regex(5), kstat(7D), sd(7D), kstat(9S)
 219 
 220 NOTES
 221      If the pattern argument contains glob or RE metacharacters which are also
 222      shell metacharacters, it will be necessary to enclose the pattern with
 223      appropriate shell quotes.
 224 
 225 illumos                        January 27, 2016                        illumos