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 "Jan 9, 2013"
   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, or a regular expression
  63 enclosed in '/' characters.
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fB-C\fR\fR
  68 .ad
  69 .RS 16n
  70 Displays output in parseable format with a colon as separator.
  71 .RE
  72 
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fB-c\fR \fIclass\fR\fR
  77 .ad
  78 .RS 16n
  79 Displays only kstats that match the specified class. \fIclass\fR is a
  80 kernel-defined string which classifies the "type" of the kstat.
  81 .RE
  82 
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fB-i\fR \fIinstance\fR\fR
  87 .ad
  88 .RS 16n
  89 Displays only kstats that match the specified instance.
  90 .RE
  91 
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fB-j\fR\fR
  96 .ad
  97 .RS 16n
  98 Displays output in JSON format.
  99 .RE
 100 
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fB-l\fR\fR
 105 .ad
 106 .RS 16n
 107 Lists matching kstat names without displaying values.
 108 .RE
 109 
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fB-m\fR \fImodule\fR\fR
 114 .ad
 115 .RS 16n
 116 Displays only kstats that match the specified module.
 117 .RE
 118 
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fB-n\fR \fIname\fR\fR
 123 .ad
 124 .RS 16n
 125 Displays only kstats that match the specified name.
 126 .RE
 127 
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fB-p\fR\fR
 132 .ad
 133 .RS 16n
 134 Displays output in parseable format. All example output in this document is
 135 given in this format. If this option is not specified, \fBkstat\fR produces
 136 output in a human-readable, table format.
 137 .RE
 138 
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fB-q\fR\fR
 143 .ad
 144 .RS 16n
 145 Displays no output, but return appropriate exit status for matches against
 146 given criteria.
 147 .RE
 148 
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fB-s\fR \fIstatistic\fR\fR
 153 .ad
 154 .RS 16n
 155 Displays only kstats that match the specified statistic.
 156 .RE
 157 
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fB-T\fR d | u\fR
 162 .ad
 163 .RS 16n
 164 Displays a time stamp before each statistics block, either in \fBdate\fR(1)
 165 format (\fBd\fR) or as an alphanumeric representation of the value returned by
 166 \fBtime\fR(2) (\fBu\fR).
 167 .RE
 168 
 169 .SH OPERANDS
 170 .sp
 171 .LP
 172 The following operands are supported:
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR\fR
 177 .ad
 178 .sp .6
 179 .RS 4n
 180 Alternate method of specifying module, instance, name, and statistic as
 181 described above. Each of the module, instance, name, or statistic specifiers
 182 may be a shell glob pattern or a regular expression enclosed by '/'
 183 characters. It is possible to use both specifier types within a single operand.
 184 Leaving a specifier empty is equivalent to using the '*' glob pattern for that
 185 specifier.
 186 .RE
 187 
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fIinterval\fR\fR
 192 .ad
 193 .sp .6
 194 .RS 4n
 195 The number of seconds between reports.
 196 .RE
 197 
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fIcount\fR\fR
 202 .ad
 203 .sp .6
 204 .RS 4n
 205 The number of reports to be printed.
 206 .RE
 207 
 208 .SH EXAMPLES
 209 .sp
 210 .LP
 211 In the following examples, all the command lines in a block produce the same
 212 output, as shown immediately below. The exact statistics and values will of
 213 course vary from machine to machine.
 214 .LP
 215 \fBExample 1 \fRUsing the \fBkstat\fR Command
 216 .sp
 217 .in +2
 218 .nf
 219 example$ \fBkstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
 220 example$ \fBkstat -p -s 'avenrun*'\fR
 221 example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
 222 example$ \fBkstat -p ':::avenrun*'\fR
 223 example$ \fBkstat -p ':::/^avenrun_[0-9]+min$/'\fR
 224 
 225 unix:0:system_misc:avenrun_15min        3
 226 unix:0:system_misc:avenrun_1min 4
 227 unix:0:system_misc:avenrun_5min 2
 228 .fi
 229 .in -2
 230 .sp
 231 
 232 .LP
 233 \fBExample 2 \fRUsing the \fBkstat\fR Command
 234 .sp
 235 .in +2
 236 .nf
 237 example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
 238 example$ \fBkstat -p cpu_stat:::/^intr/\fR
 239 
 240 cpu_stat:0:cpu_stat0:intr       29682330
 241 cpu_stat:0:cpu_stat0:intrblk    87
 242 cpu_stat:0:cpu_stat0:intrthread 15054222
 243 cpu_stat:1:cpu_stat1:intr       426073
 244 cpu_stat:1:cpu_stat1:intrblk    51
 245 cpu_stat:1:cpu_stat1:intrthread 289668
 246 cpu_stat:2:cpu_stat2:intr       134160
 247 cpu_stat:2:cpu_stat2:intrblk    0
 248 cpu_stat:2:cpu_stat2:intrthread 131
 249 cpu_stat:3:cpu_stat3:intr       196566
 250 cpu_stat:3:cpu_stat3:intrblk    30
 251 cpu_stat:3:cpu_stat3:intrthread 59626
 252 .fi
 253 .in -2
 254 .sp
 255 
 256 .LP
 257 \fBExample 3 \fRUsing the \fBkstat\fR Command
 258 .sp
 259 .in +2
 260 .nf
 261 example$ \fBkstat -p :::state ':::avenrun*'\fR
 262 example$ \fBkstat -p :::state :::/^avenrun/\fR
 263 
 264 cpu_info:0:cpu_info0:state      on-line
 265 cpu_info:1:cpu_info1:state      on-line
 266 cpu_info:2:cpu_info2:state      on-line
 267 cpu_info:3:cpu_info3:state      on-line
 268 unix:0:system_misc:avenrun_15min        4
 269 unix:0:system_misc:avenrun_1min 10
 270 unix:0:system_misc:avenrun_5min 3
 271 .fi
 272 .in -2
 273 .sp
 274 
 275 .LP
 276 \fBExample 4 \fRUsing the \fBkstat\fR Command
 277 .sp
 278 .in +2
 279 .nf
 280 example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
 281 unix:0:system_misc:avenrun_15min        15
 282 unix:0:system_misc:avenrun_1min 11
 283 unix:0:system_misc:avenrun_5min 21
 284 
 285 unix:0:system_misc:avenrun_15min        15
 286 unix:0:system_misc:avenrun_1min 11
 287 unix:0:system_misc:avenrun_5min 21
 288 
 289 unix:0:system_misc:avenrun_15min        15
 290 unix:0:system_misc:avenrun_1min 11
 291 unix:0:system_misc:avenrun_5min 21
 292 .fi
 293 .in -2
 294 .sp
 295 
 296 .LP
 297 \fBExample 5 \fRUsing the \fBkstat\fR Command
 298 .sp
 299 .in +2
 300 .nf
 301 example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
 302 Thu Jul 22 19:39:50 1999
 303 unix:0:system_misc:avenrun_15min        12
 304 unix:0:system_misc:avenrun_1min 0
 305 unix:0:system_misc:avenrun_5min 11
 306 
 307 Thu Jul 22 19:39:55 1999
 308 unix:0:system_misc:avenrun_15min        12
 309 unix:0:system_misc:avenrun_1min 0
 310 unix:0:system_misc:avenrun_5min 11
 311 .fi
 312 .in -2
 313 .sp
 314 
 315 .LP
 316 \fBExample 6 \fRUsing the \fBkstat\fR Command
 317 .sp
 318 .in +2
 319 .nf
 320 example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
 321 932668656
 322 unix:0:system_misc:avenrun_15min        14
 323 unix:0:system_misc:avenrun_1min 5
 324 unix:0:system_misc:avenrun_5min 18
 325 .fi
 326 .in -2
 327 .sp
 328 
 329 .SH EXIT STATUS
 330 .sp
 331 .LP
 332 The following exit values are returned:
 333 .sp
 334 .ne 2
 335 .na
 336 \fB\fB0\fR\fR
 337 .ad
 338 .RS 5n
 339 One or more statistics were matched.
 340 .RE
 341 
 342 .sp
 343 .ne 2
 344 .na
 345 \fB\fB1\fR\fR
 346 .ad
 347 .RS 5n
 348 No statistics were matched.
 349 .RE
 350 
 351 .sp
 352 .ne 2
 353 .na
 354 \fB\fB2\fR\fR
 355 .ad
 356 .RS 5n
 357 Invalid command line options were specified.
 358 .RE
 359 
 360 .sp
 361 .ne 2
 362 .na
 363 \fB\fB3\fR\fR
 364 .ad
 365 .RS 5n
 366 A fatal error occurred.
 367 .RE
 368 
 369 .SH FILES
 370 .sp
 371 .ne 2
 372 .na
 373 \fB\fB/dev/kstat\fR\fR
 374 .ad
 375 .RS 14n
 376 kernel statistics driver
 377 .RE
 378 
 379 .SH SEE ALSO
 380 .sp
 381 .LP
 382 \fBdate\fR(1), \fBsh\fR(1), \fBtime\fR(2), \fBgmatch\fR(3GEN),
 383 \fBkstat\fR(3KSTAT), \fBattributes\fR(5), \fBregex\fR(5), \fBkstat\fR(7D),
 384 \fBsd\fR(7D), \fBkstat\fR(9S)
 385 .SH NOTES
 386 .sp
 387 .LP
 388 If the pattern argument contains glob or RE metacharacters which are also
 389 shell metacharacters, it will be necessary to enclose the pattern with
 390 appropriate shell quotes.