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