Print this page
fix cross reference (clock_gettime, not gettimeofday).
codereview and testing fixes.
6558 kstat: desire type for timestamps
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1m/kstat.1m
+++ new/usr/src/man/man1m/kstat.1m
1 -'\" te
1 +.\" Copyright 2016 Garrett D'Amore
2 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
3 +.\" The contents of this file are subject to the terms of the Common
4 +.\" Development and Distribution License (the "License"). You may not use this
5 +.\" file except in compliance with the License. You can obtain a copy of the
6 +.\" license at usr/src/OPENSOLARIS.LICENSE or
7 +.\" http://www.opensolaris.org/os/licensing.
8 +.\"
9 +.\" See the License for the specific language governing permissions and
10 +.\" limitations under the License. When distributing Covered Code, include this
11 +.\" CDDL HEADER in each file and include the License file at
12 +.\" usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this
13 +.\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your
14 +.\" own identifying information: Portions Copyright [yyyy] [name of copyright
15 +.\" owner]
16 +.\"
17 +.Dd Jan 27, 2016
18 +.Dt KSTAT 1M
19 +.Os
20 +.Sh NAME
21 +.Nm kstat
22 +.Nd display kernel statistics
23 +.Sh SYNOPSIS
24 +.Nm
25 +.Op Fl Cjlpq
26 +.Op Fl T Cm "u|d"
27 +.Op Fl c Ar class
28 +.Op Fl m Ar module
29 +.Op Fl i Ar instance
30 +.Op Fl n Ar name
31 +.Op Fl s Ar statistic
32 +.Op Fl H Cm "o|b|u|d|n|I|Z"
33 +.Op interval Op count
34 +.Nm
35 +.Op Fl Cjlpq
36 +.Op Fl T Cm "u|d"
37 +.Op Fl c Ar class
38 +.Op Fl H Cm "o|b|u|d|n|I|Z"
39 +.Op Ar module Ns Op ":" Ns Ar instance Ns Op ":" Ns Ar name Ns Op ":" Ns Ar statistic
40 +.Ar ...
41 +.Op interval Op count
42 +.
43 +.Sh DESCRIPTION
44 +The
45 +.Nm
46 +utility examines the available kernel statistics, or kstats, on
28 47 the system and reports those statistics which match the criteria specified on
29 48 the command line. Each matching statistic is printed with its module, instance,
30 49 and name fields, as well as its actual value.
31 -.sp
32 -.LP
50 +.Lp
33 51 Kernel statistics may be published by various kernel subsystems, such as
34 52 drivers or loadable modules; each kstat has a module field that denotes its
35 53 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
54 +disks associated with the
55 +.Xr sd 7
56 +driver) for which it wishes to report
37 57 statistics, the kstat also has an instance field to index the statistics for
38 58 each entity; kstat instances are numbered starting from zero. Finally, the
39 59 kstat is given a name unique within its module.
40 -.sp
41 -.LP
60 +.Lp
42 61 Each kstat may be a special kstat type, an array of name-value pairs, or raw
43 62 data. In the name-value case, each reported value is given a label, which we
44 63 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
64 +labels for each of their values by
65 +.Va kstat ;
66 +thus, all published values can
67 +be referenced as
68 +.Ar module Ns : Ns Ar instance Ns : Ns Ar name Ns : Ns Ar statistic Ns .
69 +.Lp
49 70 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
71 +defined statistics on the system. Example invocations are provided below.
72 +.
73 +.Sh OPTIONS
74 +.
55 75 The tests specified by the following options are logically ANDed, and all
56 76 matching kstats will be selected. A regular expression containing shell
57 77 metacharacters must be protected from the shell by enclosing it with the
58 78 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
79 +.Lp
80 +The argument for the
81 +.Fl c , i , m , n , No and Fl s
62 82 options may be specified as a shell glob pattern, or a regular expression
63 83 enclosed in '/' characters.
64 -.sp
65 -.ne 2
66 -.na
67 -\fB\fB-C\fR\fR
68 -.ad
69 -.RS 16n
84 +.
85 +.Bl -tag -width Ds
86 +.It Fl C
70 87 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
88 +.It Fl H Cm o|b|u|d|n|I|Z
89 +Displays times in the specified format, after normalizing them.
90 +This can be any of the following:
91 +.Bl -tag -width Ds
92 +.It Sy o
93 +Displays snapshot and creation times as a fractional number of seconds
94 +since boot, and other times as a whole number of nanoseconds since boot.
95 +This the default behavior.
96 +.It Sy b
97 +Displays a fractional number of seconds since system boot.
98 +.It Sy u
99 +Displays a fractional number of seconds since the epoch (Jan 1, 1970 UTC).
100 +.It Sy d
101 +Displays in the same format as from
102 +.Xr date 1 .
103 +.It Sy n
104 +Displays a whole number of nanoseconds since the epoch.
105 +.It Sy I
106 +Displays an ISO 8601:2000 standard time format in the local timezone.
107 +.It Sy Z
108 +Displays an ISO 8601:2000 standard time format in UTC.
109 +.El
110 +.Lp
111 +Note that when using normalized time formats, the accuracy of
112 +the result will depend on the resolution of the realtime clock (see
113 +.Xr clock_gettime 3C ),
114 +and in no case will be more accurate to absolute time than one microsecond.
115 +However, any offset error between timestamps will be the same for all values
116 +displayed within a single kstat snapshot.
117 +.
118 +.It Fl c Ar class
119 +Displays only kstats that match the specified class.
120 +.Ar class
121 +is a kernel-defined string which classifies the "type" of the kstat.
122 +.It Fl i Ar instance
89 123 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
124 +.It Fl j
98 125 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
126 +.It Fl l
107 127 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
128 +.It Fl m Ar module
116 129 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
130 +.It Fl n Ar name
125 131 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
132 +.It Fl p
134 133 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
134 +given in this format. If this option is not specified,
135 +.Nm
136 +produces output in a human-readable, table format.
137 +.It Fl q
145 138 Displays no output, but return appropriate exit status for matches against
146 139 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
140 +.It Fl s Ar statistic
155 141 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)
142 +.It Fl T Cm "d|u"
143 +Displays a time stamp before each statistics block, either in
144 +.Xr date 1
165 145 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
146 +.Xr time 2
147 +(\fBu\fR).
148 +.El
149 +.Sh OPERANDS
172 150 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
151 +.Bl -tag -width Ds
152 +.It Ar module Ns : Ns Ar instance Ns : Ns Ar name Ns : Ns Ar statistic Ns
180 153 Alternate method of specifying module, instance, name, and statistic as
181 154 described above. Each of the module, instance, name, or statistic specifiers
182 155 may be a shell glob pattern or a regular expression enclosed by '/'
183 156 characters. It is possible to use both specifier types within a single operand.
184 157 Leaving a specifier empty is equivalent to using the '*' glob pattern for that
185 158 specifier.
186 -.RE
187 -
188 -.sp
189 -.ne 2
190 -.na
191 -\fB\fIinterval\fR\fR
192 -.ad
193 -.sp .6
194 -.RS 4n
159 +.It Ar interval
195 160 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
161 +.It Ar count
205 162 The number of reports to be printed.
206 -.RE
207 -
208 -.SH EXAMPLES
209 -.sp
210 -.LP
163 +.El
164 +.Sh FILES
165 +.Bl -tag -width Ds
166 +.It Pa /dev/kstat
167 +kernel statistics driver
168 +.El
169 +.Sh EXIT STATUS
170 +The following exit values are returned:
171 +.Lp
172 +.Bl -tag -width Ds -compact
173 +.It 0
174 +One or more statistics were matched.
175 +.It 1
176 +No statistics were matched.
177 +.It 2
178 +Invalid command line options were specified.
179 +.It 3
180 +A fatal error occurred.
181 +.El
182 +.Sh EXAMPLES
211 183 In the following examples, all the command lines in a block produce the same
212 184 output, as shown immediately below. The exact statistics and values will of
213 185 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
186 +.
187 +.Ss Example 1: Using the kstat Command
188 +.Bd -literal -offset indent
189 +example$ \fBlstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
220 190 example$ \fBkstat -p -s 'avenrun*'\fR
221 191 example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
222 192 example$ \fBkstat -p ':::avenrun*'\fR
223 193 example$ \fBkstat -p ':::/^avenrun_[0-9]+min$/'\fR
224 -
194 +.sp
225 195 unix:0:system_misc:avenrun_15min 3
226 196 unix:0:system_misc:avenrun_1min 4
227 197 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
198 +.Ed
199 +.
200 +.Ss Example 2: Using the kstat Command
201 +.Bd -literal -offset indent
237 202 example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
238 203 example$ \fBkstat -p cpu_stat:::/^intr/\fR
239 -
204 +.sp
240 205 cpu_stat:0:cpu_stat0:intr 29682330
241 206 cpu_stat:0:cpu_stat0:intrblk 87
242 207 cpu_stat:0:cpu_stat0:intrthread 15054222
243 208 cpu_stat:1:cpu_stat1:intr 426073
244 209 cpu_stat:1:cpu_stat1:intrblk 51
245 210 cpu_stat:1:cpu_stat1:intrthread 289668
246 211 cpu_stat:2:cpu_stat2:intr 134160
247 212 cpu_stat:2:cpu_stat2:intrblk 0
248 213 cpu_stat:2:cpu_stat2:intrthread 131
249 214 cpu_stat:3:cpu_stat3:intr 196566
250 215 cpu_stat:3:cpu_stat3:intrblk 30
251 216 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
217 +.Ed
218 +.
219 +.Ss Example 3: Using the kstat Command
220 +.Bd -literal -offset indent
261 221 example$ \fBkstat -p :::state ':::avenrun*'\fR
262 222 example$ \fBkstat -p :::state :::/^avenrun/\fR
263 -
223 +.sp
264 224 cpu_info:0:cpu_info0:state on-line
265 225 cpu_info:1:cpu_info1:state on-line
266 226 cpu_info:2:cpu_info2:state on-line
267 227 cpu_info:3:cpu_info3:state on-line
268 228 unix:0:system_misc:avenrun_15min 4
269 229 unix:0:system_misc:avenrun_1min 10
270 230 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
231 +.Ed
232 +.
233 +.Ss Example 4: Using the kstat Command
234 +.Bd -literal -offset indent
280 235 example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
281 236 unix:0:system_misc:avenrun_15min 15
282 237 unix:0:system_misc:avenrun_1min 11
283 238 unix:0:system_misc:avenrun_5min 21
284 -
239 +.sp
285 240 unix:0:system_misc:avenrun_15min 15
286 241 unix:0:system_misc:avenrun_1min 11
287 242 unix:0:system_misc:avenrun_5min 21
288 -
243 +.sp
289 244 unix:0:system_misc:avenrun_15min 15
290 245 unix:0:system_misc:avenrun_1min 11
291 246 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
247 +.Ed
248 +.
249 +.Ss Example 5: Using the kstat Command
250 +.Bd -literal -offset indent
301 251 example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
302 252 Thu Jul 22 19:39:50 1999
303 253 unix:0:system_misc:avenrun_15min 12
304 254 unix:0:system_misc:avenrun_1min 0
305 255 unix:0:system_misc:avenrun_5min 11
306 -
256 +.sp
307 257 Thu Jul 22 19:39:55 1999
308 258 unix:0:system_misc:avenrun_15min 12
309 259 unix:0:system_misc:avenrun_1min 0
310 260 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
261 +.Ed
262 +.
263 +.Ss Example 6: Using the kstat Command
264 +.Bd -literal -offset indent
320 265 example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
321 266 932668656
322 267 unix:0:system_misc:avenrun_15min 14
323 268 unix:0:system_misc:avenrun_1min 5
324 269 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
270 +.Ed
271 +.Sh SEE ALSO
272 +.Xr date 1 ,
273 +.Xr sh 1 ,
274 +.Xr time 2 ,
275 +.Xr clock_gettime 3C ,
276 +.Xr gmatch 3GEN ,
277 +.Xr kstat 3KSTAT ,
278 +.Xr regex 5 ,
279 +.Xr kstat 7D ,
280 +.Xr sd 7D ,
281 +.Xr kstat 9S
282 +.Sh NOTES
388 283 If the pattern argument contains glob or RE metacharacters which are also
389 284 shell metacharacters, it will be necessary to enclose the pattern with
390 285 appropriate shell quotes.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX