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"
8 kstat \- display kernel statistics
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]
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]]]]...
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.
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.
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.
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.
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
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.
70 Displays output in parseable format with a colon as separator.
76 \fB\fB-c\fR \fIclass\fR\fR
79 Displays only kstats that match the specified class. \fIclass\fR is a
80 kernel-defined string which classifies the "type" of the kstat.
86 \fB\fB-i\fR \fIinstance\fR\fR
89 Displays only kstats that match the specified instance.
98 Displays output in JSON format.
107 Lists matching kstat names without displaying values.
113 \fB\fB-m\fR \fImodule\fR\fR
116 Displays only kstats that match the specified module.
122 \fB\fB-n\fR \fIname\fR\fR
125 Displays only kstats that match the specified name.
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.
145 Displays no output, but return appropriate exit status for matches against
152 \fB\fB-s\fR \fIstatistic\fR\fR
155 Displays only kstats that match the specified statistic.
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).
172 The following operands are supported:
176 \fB\fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR\fR
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
195 The number of seconds between reports.
205 The number of reports to be printed.
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.
215 \fBExample 1 \fRUsing the \fBkstat\fR Command
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
225 unix:0:system_misc:avenrun_15min 3
226 unix:0:system_misc:avenrun_1min 4
227 unix:0:system_misc:avenrun_5min 2
233 \fBExample 2 \fRUsing the \fBkstat\fR Command
237 example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
238 example$ \fBkstat -p cpu_stat:::/^intr/\fR
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
257 \fBExample 3 \fRUsing the \fBkstat\fR Command
261 example$ \fBkstat -p :::state ':::avenrun*'\fR
262 example$ \fBkstat -p :::state :::/^avenrun/\fR
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
276 \fBExample 4 \fRUsing the \fBkstat\fR Command
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
285 unix:0:system_misc:avenrun_15min 15
286 unix:0:system_misc:avenrun_1min 11
287 unix:0:system_misc:avenrun_5min 21
289 unix:0:system_misc:avenrun_15min 15
290 unix:0:system_misc:avenrun_1min 11
291 unix:0:system_misc:avenrun_5min 21
297 \fBExample 5 \fRUsing the \fBkstat\fR Command
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
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
316 \fBExample 6 \fRUsing the \fBkstat\fR Command
320 example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
322 unix:0:system_misc:avenrun_15min 14
323 unix:0:system_misc:avenrun_1min 5
324 unix:0:system_misc:avenrun_5min 18
332 The following exit values are returned:
339 One or more statistics were matched.
348 No statistics were matched.
357 Invalid command line options were specified.
366 A fatal error occurred.
373 \fB\fB/dev/kstat\fR\fR
376 kernel statistics driver
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)
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.