1 '\" te
   2 .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KSTAT 1M "Nov 22, 2012"
   7 .SH NAME
   8 kstat \- display kernel statistics
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBkstat\fR [\fB-Cjlpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR] [\fB-m\fR \fImodule\fR]
  13      [\fB-i\fR \fIinstance\fR] [\fB-n\fR \fIname\fR] [\fB-s\fR \fIstatistic\fR]
  14      [interval [count]]
  15 .fi
  16 
  17 .LP
  18 .nf
  19 \fBkstat\fR [\fB-Cjlpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR]
  20      [\fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR]...
  21      [interval [count]]
  22 .fi
  23 
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 The \fBkstat\fR utility examines the available kernel statistics, or kstats, on
  28 the system and reports those statistics which match the criteria specified on
  29 the command line. Each matching statistic is printed with its module, instance,
  30 and name fields, as well as its actual value.
  31 .sp
  32 .LP
  33 Kernel statistics may be published by various kernel subsystems, such as
  34 drivers or loadable modules; each kstat has a module field that denotes its
  35 publisher. Since each module might have countable entities (such as multiple
  36 disks associated with the \fBsd\fR(7D) driver) for which it wishes to report
  37 statistics, the kstat also has an instance field to index the statistics for
  38 each entity; kstat instances are numbered starting from zero. Finally, the
  39 kstat is given a name unique within its module.
  40 .sp
  41 .LP
  42 Each kstat may be a special kstat type, an array of name-value pairs, or raw
  43 data. In the name-value case, each reported value is given a label, which we
  44 refer to as the statistic. Known raw and special kstats are given statistic
  45 labels for each of their values by \fBkstat\fR; thus, all published values can
  46 be referenced as \fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR.
  47 .sp
  48 .LP
  49 When invoked without any module operands or options, kstat will match all
  50 defined statistics on the system. Example invocations are provided below. All
  51 times are displayed as fractional seconds since system boot.
  52 .SH OPTIONS
  53 .sp
  54 .LP
  55 The tests specified by the following options are logically ANDed, and all
  56 matching kstats will be selected. A regular expression containing shell
  57 metacharacters must be protected from the shell by enclosing it with the
  58 appropriate quotes.
  59 .sp
  60 .LP
  61 The argument for the \fB-c\fR, \fB-i\fR, \fB-m\fR, \fB-n\fR, and \fB-s\fR
  62 options may be specified as a shell glob pattern.
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fB-C\fR\fR
  67 .ad
  68 .RS 16n
  69 Displays output in parseable format with a colon as separator.
  70 .RE
  71 
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fB-c\fR \fIclass\fR\fR
  76 .ad
  77 .RS 16n
  78 Displays only kstats that match the specified class. \fIclass\fR is a
  79 kernel-defined string which classifies the "type" of the kstat.
  80 .RE
  81 
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fB-i\fR \fIinstance\fR\fR
  86 .ad
  87 .RS 16n
  88 Displays only kstats that match the specified instance.
  89 .RE
  90 
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fB-j\fR\fR
  95 .ad
  96 .RS 16n
  97 Displays output in JSON format.
  98 .RE
  99 
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fB-l\fR\fR
 104 .ad
 105 .RS 16n
 106 Lists matching kstat names without displaying values.
 107 .RE
 108 
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fB-m\fR \fImodule\fR\fR
 113 .ad
 114 .RS 16n
 115 Displays only kstats that match the specified module.
 116 .RE
 117 
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fB-n\fR \fIname\fR\fR
 122 .ad
 123 .RS 16n
 124 Displays only kstats that match the specified name.
 125 .RE
 126 
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fB-p\fR\fR
 131 .ad
 132 .RS 16n
 133 Displays output in parseable format. All example output in this document is
 134 given in this format. If this option is not specified, \fBkstat\fR produces
 135 output in a human-readable, table format.
 136 .RE
 137 
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fB-q\fR\fR
 142 .ad
 143 .RS 16n
 144 Displays no output, but return appropriate exit status for matches against
 145 given criteria.
 146 .RE
 147 
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fB-s\fR \fIstatistic\fR\fR
 152 .ad
 153 .RS 16n
 154 Displays only kstats that match the specified statistic.
 155 .RE
 156 
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fB-T\fR d | u\fR
 161 .ad
 162 .RS 16n
 163 Displays a time stamp before each statistics block, either in \fBdate\fR(1)
 164 format (\fBd\fR) or as an alphanumeric representation of the value returned by
 165 \fBtime\fR(2) (\fBu\fR).
 166 .RE
 167 
 168 .SH OPERANDS
 169 .sp
 170 .LP
 171 The following operands are supported:
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR\fR
 176 .ad
 177 .sp .6
 178 .RS 4n
 179 Alternate method of specifying module, instance, name, and statistic as
 180 described above. Each of the module, instance, name, or statistic specifiers
 181 may be a shell glob pattern.
 182 It is possible to use both specifier types within a single operand.
 183 Leaving a specifier empty is equivalent to using the '*' glob pattern for that
 184 specifier.
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fIinterval\fR\fR
 191 .ad
 192 .sp .6
 193 .RS 4n
 194 The number of seconds between reports.
 195 .RE
 196 
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fIcount\fR\fR
 201 .ad
 202 .sp .6
 203 .RS 4n
 204 The number of reports to be printed.
 205 .RE
 206 
 207 .SH EXAMPLES
 208 .sp
 209 .LP
 210 In the following examples, all the command lines in a block produce the same
 211 output, as shown immediately below. The exact statistics and values will of
 212 course vary from machine to machine.
 213 .LP
 214 \fBExample 1 \fRUsing the \fBkstat\fR Command
 215 .sp
 216 .in +2
 217 .nf
 218 example$ \fBkstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
 219 example$ \fBkstat -p -s 'avenrun*'\fR
 220 example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
 221 example$ \fBkstat -p ':::avenrun*'\fR
 222 example$ \fBkstat -p ':::avenrun*min$'\fR
 223 
 224 unix:0:system_misc:avenrun_15min        3
 225 unix:0:system_misc:avenrun_1min 4
 226 unix:0:system_misc:avenrun_5min 2
 227 .fi
 228 .in -2
 229 .sp
 230 
 231 .LP
 232 \fBExample 2 \fRUsing the \fBkstat\fR Command
 233 .sp
 234 .in +2
 235 .nf
 236 example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
 237 example$ \fBkstat -p 'cpu_stat:::intr*'\fR
 238 
 239 cpu_stat:0:cpu_stat0:intr       29682330
 240 cpu_stat:0:cpu_stat0:intrblk    87
 241 cpu_stat:0:cpu_stat0:intrthread 15054222
 242 cpu_stat:1:cpu_stat1:intr       426073
 243 cpu_stat:1:cpu_stat1:intrblk    51
 244 cpu_stat:1:cpu_stat1:intrthread 289668
 245 cpu_stat:2:cpu_stat2:intr       134160
 246 cpu_stat:2:cpu_stat2:intrblk    0
 247 cpu_stat:2:cpu_stat2:intrthread 131
 248 cpu_stat:3:cpu_stat3:intr       196566
 249 cpu_stat:3:cpu_stat3:intrblk    30
 250 cpu_stat:3:cpu_stat3:intrthread 59626
 251 .fi
 252 .in -2
 253 .sp
 254 
 255 .LP
 256 \fBExample 3 \fRUsing the \fBkstat\fR Command
 257 .sp
 258 .in +2
 259 .nf
 260 example$ \fBkstat -p :::state ':::avenrun*'\fR
 261 
 262 cpu_info:0:cpu_info0:state      on-line
 263 cpu_info:1:cpu_info1:state      on-line
 264 cpu_info:2:cpu_info2:state      on-line
 265 cpu_info:3:cpu_info3:state      on-line
 266 unix:0:system_misc:avenrun_15min        4
 267 unix:0:system_misc:avenrun_1min 10
 268 unix:0:system_misc:avenrun_5min 3
 269 .fi
 270 .in -2
 271 .sp
 272 
 273 .LP
 274 \fBExample 4 \fRUsing the \fBkstat\fR Command
 275 .sp
 276 .in +2
 277 .nf
 278 example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
 279 unix:0:system_misc:avenrun_15min        15
 280 unix:0:system_misc:avenrun_1min 11
 281 unix:0:system_misc:avenrun_5min 21
 282 
 283 unix:0:system_misc:avenrun_15min        15
 284 unix:0:system_misc:avenrun_1min 11
 285 unix:0:system_misc:avenrun_5min 21
 286 
 287 unix:0:system_misc:avenrun_15min        15
 288 unix:0:system_misc:avenrun_1min 11
 289 unix:0:system_misc:avenrun_5min 21
 290 .fi
 291 .in -2
 292 .sp
 293 
 294 .LP
 295 \fBExample 5 \fRUsing the \fBkstat\fR Command
 296 .sp
 297 .in +2
 298 .nf
 299 example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
 300 Thu Jul 22 19:39:50 1999
 301 unix:0:system_misc:avenrun_15min        12
 302 unix:0:system_misc:avenrun_1min 0
 303 unix:0:system_misc:avenrun_5min 11
 304 
 305 Thu Jul 22 19:39:55 1999
 306 unix:0:system_misc:avenrun_15min        12
 307 unix:0:system_misc:avenrun_1min 0
 308 unix:0:system_misc:avenrun_5min 11
 309 .fi
 310 .in -2
 311 .sp
 312 
 313 .LP
 314 \fBExample 6 \fRUsing the \fBkstat\fR Command
 315 .sp
 316 .in +2
 317 .nf
 318 example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
 319 932668656
 320 unix:0:system_misc:avenrun_15min        14
 321 unix:0:system_misc:avenrun_1min 5
 322 unix:0:system_misc:avenrun_5min 18
 323 .fi
 324 .in -2
 325 .sp
 326 
 327 .SH EXIT STATUS
 328 .sp
 329 .LP
 330 The following exit values are returned:
 331 .sp
 332 .ne 2
 333 .na
 334 \fB\fB0\fR\fR
 335 .ad
 336 .RS 5n
 337 One or more statistics were matched.
 338 .RE
 339 
 340 .sp
 341 .ne 2
 342 .na
 343 \fB\fB1\fR\fR
 344 .ad
 345 .RS 5n
 346 No statistics were matched.
 347 .RE
 348 
 349 .sp
 350 .ne 2
 351 .na
 352 \fB\fB2\fR\fR
 353 .ad
 354 .RS 5n
 355 Invalid command line options were specified.
 356 .RE
 357 
 358 .sp
 359 .ne 2
 360 .na
 361 \fB\fB3\fR\fR
 362 .ad
 363 .RS 5n
 364 A fatal error occurred.
 365 .RE
 366 
 367 .SH FILES
 368 .sp
 369 .ne 2
 370 .na
 371 \fB\fB/dev/kstat\fR\fR
 372 .ad
 373 .RS 14n
 374 kernel statistics driver
 375 .RE
 376 
 377 .SH SEE ALSO
 378 .sp
 379 .LP
 380 \fBdate\fR(1), \fBsh\fR(1), \fBtime\fR(2), \fBgmatch\fR(3GEN),
 381 \fBkstat\fR(3KSTAT), \fBattributes\fR(5), \fBkstat\fR(7D), \fBsd\fR(7D),
 382 \fBkstat\fR(9S)
 383 .SH NOTES
 384 .sp
 385 .LP
 386 If the pattern argument contains glob metacharacters which are also
 387 shell metacharacters, it will be necessary to enclose the pattern with
 388 appropriate shell quotes.