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