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.man.txt
+++ new/usr/src/man/man1m/kstat.1m.man.txt
1 1 KSTAT(1M) Maintenance Commands KSTAT(1M)
2 2
3 -
4 -
5 3 NAME
6 - kstat - display kernel statistics
4 + kstat - display kernel statistics
7 5
8 6 SYNOPSIS
9 - kstat [-Cjlpq] [-T u | d ] [-c class] [-m module]
10 - [-i instance] [-n name] [-s statistic]
11 - [interval [count]]
7 + kstat [-Cjlpq] [-T u|d] [-c class] [-m module] [-i instance] [-n name]
8 + [-s statistic] [-H o|b|u|d|n|I|Z] [interval [count]]
9 + kstat [-Cjlpq] [-T u|d] [-c class] [-H o|b|u|d|n|I|Z]
10 + [module[:instance[:name[:statistic]]]] ... [interval [count]]
12 11
13 -
14 - kstat [-Cjlpq] [-T u | d ] [-c class]
15 - [module[:instance[:name[:statistic]]]]...
16 - [interval [count]]
17 -
18 -
19 12 DESCRIPTION
20 - The kstat utility examines the available kernel statistics, or kstats,
21 - on the system and reports those statistics which match the criteria
22 - specified on the command line. Each matching statistic is printed with
23 - its module, instance, and name fields, as well as its actual value.
13 + The kstat utility examines the available kernel statistics, or kstats, on
14 + the system and reports those statistics which match the criteria
15 + specified on the command line. Each matching statistic is printed with
16 + its module, instance, and name fields, as well as its actual value.
24 17
18 + Kernel statistics may be published by various kernel subsystems, such as
19 + drivers or loadable modules; each kstat has a module field that denotes
20 + its publisher. Since each module might have countable entities (such as
21 + multiple disks associated with the sd(7) driver) for which it wishes to
22 + report statistics, the kstat also has an instance field to index the
23 + statistics for each entity; kstat instances are numbered starting from
24 + zero. Finally, the kstat is given a name unique within its module.
25 25
26 - Kernel statistics may be published by various kernel subsystems, such
27 - as drivers or loadable modules; each kstat has a module field that
28 - denotes its publisher. Since each module might have countable entities
29 - (such as multiple disks associated with the sd(7D) driver) for which it
30 - wishes to report statistics, the kstat also has an instance field to
31 - index the statistics for each entity; kstat instances are numbered
32 - starting from zero. Finally, the kstat is given a name unique within
33 - its module.
26 + Each kstat may be a special kstat type, an array of name-value pairs, or
27 + raw data. In the name-value case, each reported value is given a label,
28 + which we refer to as the statistic. Known raw and special kstats are
29 + given statistic labels for each of their values by kstat; thus, all
30 + published values can be referenced as module:instance:name:statistic.
34 31
32 + When invoked without any module operands or options, kstat will match all
33 + defined statistics on the system. Example invocations are provided below.
35 34
36 - Each kstat may be a special kstat type, an array of name-value pairs,
37 - or raw data. In the name-value case, each reported value is given a
38 - label, which we refer to as the statistic. Known raw and special kstats
39 - are given statistic labels for each of their values by kstat; thus, all
40 - published values can be referenced as module:instance:name:statistic.
41 -
42 -
43 - When invoked without any module operands or options, kstat will match
44 - all defined statistics on the system. Example invocations are provided
45 - below. All times are displayed as fractional seconds since system boot.
46 -
47 35 OPTIONS
48 - The tests specified by the following options are logically ANDed, and
49 - all matching kstats will be selected. A regular expression containing
50 - shell metacharacters must be protected from the shell by enclosing it
51 - with the appropriate quotes.
36 + The tests specified by the following options are logically ANDed, and all
37 + matching kstats will be selected. A regular expression containing shell
38 + metacharacters must be protected from the shell by enclosing it with the
39 + appropriate quotes.
52 40
41 + The argument for the -c, -i, -m, -n, and -s options may be specified as a
42 + shell glob pattern, or a regular expression enclosed in '/' characters.
53 43
54 - The argument for the -c, -i, -m, -n, and -s options may be specified as
55 - a shell glob pattern, or a regular expression enclosed in '/'
56 - characters.
44 + -C Displays output in parseable format with a colon as separator.
57 45
58 - -C
59 - Displays output in parseable format with a colon as
60 - separator.
46 + -H o|b|u|d|n|I|Z
47 + Displays times in the specified format, after normalizing them.
48 + This can be any of the following:
61 49
50 + o Displays snapshot and creation times as a fractional
51 + number of seconds since boot, and other times as a whole
52 + number of nanoseconds since boot. This the default
53 + behavior.
62 54
63 - -c class
64 - Displays only kstats that match the specified class.
65 - class is a kernel-defined string which classifies the
66 - "type" of the kstat.
55 + b Displays a fractional number of seconds since system
56 + boot.
67 57
58 + u Displays a fractional number of seconds since the epoch
59 + (Jan 1, 1970 UTC).
68 60
69 - -i instance
70 - Displays only kstats that match the specified instance.
61 + d Displays in the same format as from date(1).
71 62
63 + n Displays a whole number of nanoseconds since the epoch.
72 64
73 - -j
74 - Displays output in JSON format.
65 + I Displays an ISO 8601:2000 standard time format in the
66 + local timezone.
75 67
68 + Z Displays an ISO 8601:2000 standard time format in UTC.
76 69
77 - -l
78 - Lists matching kstat names without displaying values.
70 + Note that when using normalized time formats, the accuracy of the
71 + result will depend on the resolution of the realtime clock (see
72 + clock_gettime(3C) ), and in no case will be more accurate to
73 + absolute time than one microsecond. However, any offset error
74 + between timestamps will be the same for all values displayed
75 + within a single kstat snapshot.
79 76
77 + -c class
78 + Displays only kstats that match the specified class. class is a
79 + kernel-defined string which classifies the "type" of the kstat.
80 80
81 - -m module
82 - Displays only kstats that match the specified module.
81 + -i instance
82 + Displays only kstats that match the specified instance.
83 83
84 + -j Displays output in JSON format.
84 85
85 - -n name
86 - Displays only kstats that match the specified name.
86 + -l Lists matching kstat names without displaying values.
87 87
88 + -m module
89 + Displays only kstats that match the specified module.
88 90
89 - -p
90 - Displays output in parseable format. All example output
91 - in this document is given in this format. If this
92 - option is not specified, kstat produces output in a
93 - human-readable, table format.
91 + -n name
92 + Displays only kstats that match the specified name.
94 93
94 + -p Displays output in parseable format. All example output in this
95 + document is given in this format. If this option is not
96 + specified, kstat produces output in a human-readable, table
97 + format.
95 98
96 - -q
97 - Displays no output, but return appropriate exit status
98 - for matches against given criteria.
99 + -q Displays no output, but return appropriate exit status for
100 + matches against given criteria.
99 101
102 + -s statistic
103 + Displays only kstats that match the specified statistic.
100 104
101 - -s statistic
102 - Displays only kstats that match the specified
103 - statistic.
105 + -T d|u Displays a time stamp before each statistics block, either in
106 + date(1) format (d) or as an alphanumeric representation of the
107 + value returned by time(2) (u).
104 108
105 -
106 - -T d | u
107 - Displays a time stamp before each statistics block,
108 - either in date(1) format (d) or as an alphanumeric
109 - representation of the value returned by time(2) (u).
110 -
111 -
112 109 OPERANDS
113 - The following operands are supported:
110 + The following operands are supported:
114 111
115 - module:instance:name:statistic
112 + module:instance:name:statistic
113 + Alternate method of specifying module, instance, name, and
114 + statistic as described above. Each of the module, instance, name,
115 + or statistic specifiers may be a shell glob pattern or a regular
116 + expression enclosed by '/' characters. It is possible to use both
117 + specifier types within a single operand. Leaving a specifier
118 + empty is equivalent to using the '*' glob pattern for that
119 + specifier.
116 120
117 - Alternate method of specifying module, instance, name, and
118 - statistic as described above. Each of the module, instance, name,
119 - or statistic specifiers may be a shell glob pattern or a regular
120 - expression enclosed by '/' characters. It is possible to use both
121 - specifier types within a single operand. Leaving a specifier empty
122 - is equivalent to using the '*' glob pattern for that specifier.
121 + interval
122 + The number of seconds between reports.
123 123
124 + count The number of reports to be printed.
124 125
125 - interval
126 +FILES
127 + /dev/kstat
128 + kernel statistics driver
126 129
127 - The number of seconds between reports.
130 +EXIT STATUS
131 + The following exit values are returned:
128 132
133 + 0 One or more statistics were matched.
134 + 1 No statistics were matched.
135 + 2 Invalid command line options were specified.
136 + 3 A fatal error occurred.
129 137
130 - count
131 -
132 - The number of reports to be printed.
133 -
134 -
135 138 EXAMPLES
136 - In the following examples, all the command lines in a block produce the
137 - same output, as shown immediately below. The exact statistics and
138 - values will of course vary from machine to machine.
139 + In the following examples, all the command lines in a block produce the
140 + same output, as shown immediately below. The exact statistics and values
141 + will of course vary from machine to machine.
139 142
140 - Example 1 Using the kstat Command
143 + Example 1: Using the kstat Command
144 + example$ lstat -p -m unix -i 0 -n system_misc -s 'avenrun*'
145 + example$ kstat -p -s 'avenrun*'
146 + example$ kstat -p 'unix:0:system_misc:avenrun*'
147 + example$ kstat -p ':::avenrun*'
148 + example$ kstat -p ':::/^avenrun_[0-9]+min$/'
141 149
142 - example$ kstat -p -m unix -i 0 -n system_misc -s 'avenrun*'
143 - example$ kstat -p -s 'avenrun*'
144 - example$ kstat -p 'unix:0:system_misc:avenrun*'
145 - example$ kstat -p ':::avenrun*'
146 - example$ kstat -p ':::/^avenrun_[0-9]+min$/'
150 + unix:0:system_misc:avenrun_15min 3
151 + unix:0:system_misc:avenrun_1min 4
152 + unix:0:system_misc:avenrun_5min 2
147 153
148 - unix:0:system_misc:avenrun_15min 3
149 - unix:0:system_misc:avenrun_1min 4
150 - unix:0:system_misc:avenrun_5min 2
154 + Example 2: Using the kstat Command
155 + example$ kstat -p -m cpu_stat -s 'intr*'
156 + example$ kstat -p cpu_stat:::/^intr/
151 157
158 + cpu_stat:0:cpu_stat0:intr 29682330
159 + cpu_stat:0:cpu_stat0:intrblk 87
160 + cpu_stat:0:cpu_stat0:intrthread 15054222
161 + cpu_stat:1:cpu_stat1:intr 426073
162 + cpu_stat:1:cpu_stat1:intrblk 51
163 + cpu_stat:1:cpu_stat1:intrthread 289668
164 + cpu_stat:2:cpu_stat2:intr 134160
165 + cpu_stat:2:cpu_stat2:intrblk 0
166 + cpu_stat:2:cpu_stat2:intrthread 131
167 + cpu_stat:3:cpu_stat3:intr 196566
168 + cpu_stat:3:cpu_stat3:intrblk 30
169 + cpu_stat:3:cpu_stat3:intrthread 59626
152 170
171 + Example 3: Using the kstat Command
172 + example$ kstat -p :::state ':::avenrun*'
173 + example$ kstat -p :::state :::/^avenrun/
153 174
154 - Example 2 Using the kstat Command
175 + cpu_info:0:cpu_info0:state on-line
176 + cpu_info:1:cpu_info1:state on-line
177 + cpu_info:2:cpu_info2:state on-line
178 + cpu_info:3:cpu_info3:state on-line
179 + unix:0:system_misc:avenrun_15min 4
180 + unix:0:system_misc:avenrun_1min 10
181 + unix:0:system_misc:avenrun_5min 3
155 182
156 - example$ kstat -p -m cpu_stat -s 'intr*'
157 - example$ kstat -p cpu_stat:::/^intr/
183 + Example 4: Using the kstat Command
184 + example$ kstat -p 'unix:0:system_misc:avenrun*' 1 3
185 + unix:0:system_misc:avenrun_15min 15
186 + unix:0:system_misc:avenrun_1min 11
187 + unix:0:system_misc:avenrun_5min 21
158 188
159 - cpu_stat:0:cpu_stat0:intr 29682330
160 - cpu_stat:0:cpu_stat0:intrblk 87
161 - cpu_stat:0:cpu_stat0:intrthread 15054222
162 - cpu_stat:1:cpu_stat1:intr 426073
163 - cpu_stat:1:cpu_stat1:intrblk 51
164 - cpu_stat:1:cpu_stat1:intrthread 289668
165 - cpu_stat:2:cpu_stat2:intr 134160
166 - cpu_stat:2:cpu_stat2:intrblk 0
167 - cpu_stat:2:cpu_stat2:intrthread 131
168 - cpu_stat:3:cpu_stat3:intr 196566
169 - cpu_stat:3:cpu_stat3:intrblk 30
170 - cpu_stat:3:cpu_stat3:intrthread 59626
189 + unix:0:system_misc:avenrun_15min 15
190 + unix:0:system_misc:avenrun_1min 11
191 + unix:0:system_misc:avenrun_5min 21
171 192
193 + unix:0:system_misc:avenrun_15min 15
194 + unix:0:system_misc:avenrun_1min 11
195 + unix:0:system_misc:avenrun_5min 21
172 196
197 + Example 5: Using the kstat Command
198 + example$ kstat -p -T d 'unix:0:system_misc:avenrun*' 5 2
199 + Thu Jul 22 19:39:50 1999
200 + unix:0:system_misc:avenrun_15min 12
201 + unix:0:system_misc:avenrun_1min 0
202 + unix:0:system_misc:avenrun_5min 11
173 203
174 - Example 3 Using the kstat Command
204 + Thu Jul 22 19:39:55 1999
205 + unix:0:system_misc:avenrun_15min 12
206 + unix:0:system_misc:avenrun_1min 0
207 + unix:0:system_misc:avenrun_5min 11
175 208
176 - example$ kstat -p :::state ':::avenrun*'
177 - example$ kstat -p :::state :::/^avenrun/
209 + Example 6: Using the kstat Command
210 + example$ kstat -p -T u 'unix:0:system_misc:avenrun*'
211 + 932668656
212 + unix:0:system_misc:avenrun_15min 14
213 + unix:0:system_misc:avenrun_1min 5
214 + unix:0:system_misc:avenrun_5min 18
178 215
179 - cpu_info:0:cpu_info0:state on-line
180 - cpu_info:1:cpu_info1:state on-line
181 - cpu_info:2:cpu_info2:state on-line
182 - cpu_info:3:cpu_info3:state on-line
183 - unix:0:system_misc:avenrun_15min 4
184 - unix:0:system_misc:avenrun_1min 10
185 - unix:0:system_misc:avenrun_5min 3
186 -
187 -
188 -
189 - Example 4 Using the kstat Command
190 -
191 - example$ kstat -p 'unix:0:system_misc:avenrun*' 1 3
192 - unix:0:system_misc:avenrun_15min 15
193 - unix:0:system_misc:avenrun_1min 11
194 - unix:0:system_misc:avenrun_5min 21
195 -
196 - unix:0:system_misc:avenrun_15min 15
197 - unix:0:system_misc:avenrun_1min 11
198 - unix:0:system_misc:avenrun_5min 21
199 -
200 - unix:0:system_misc:avenrun_15min 15
201 - unix:0:system_misc:avenrun_1min 11
202 - unix:0:system_misc:avenrun_5min 21
203 -
204 -
205 -
206 - Example 5 Using the kstat Command
207 -
208 - example$ kstat -p -T d 'unix:0:system_misc:avenrun*' 5 2
209 - Thu Jul 22 19:39:50 1999
210 - unix:0:system_misc:avenrun_15min 12
211 - unix:0:system_misc:avenrun_1min 0
212 - unix:0:system_misc:avenrun_5min 11
213 -
214 - Thu Jul 22 19:39:55 1999
215 - unix:0:system_misc:avenrun_15min 12
216 - unix:0:system_misc:avenrun_1min 0
217 - unix:0:system_misc:avenrun_5min 11
218 -
219 -
220 -
221 - Example 6 Using the kstat Command
222 -
223 - example$ kstat -p -T u 'unix:0:system_misc:avenrun*'
224 - 932668656
225 - unix:0:system_misc:avenrun_15min 14
226 - unix:0:system_misc:avenrun_1min 5
227 - unix:0:system_misc:avenrun_5min 18
228 -
229 -
230 -
231 -EXIT STATUS
232 - The following exit values are returned:
233 -
234 - 0
235 - One or more statistics were matched.
236 -
237 -
238 - 1
239 - No statistics were matched.
240 -
241 -
242 - 2
243 - Invalid command line options were specified.
244 -
245 -
246 - 3
247 - A fatal error occurred.
248 -
249 -
250 -FILES
251 - /dev/kstat
252 - kernel statistics driver
253 -
254 -
255 216 SEE ALSO
256 - date(1), sh(1), time(2), gmatch(3GEN), kstat(3KSTAT), attributes(5),
257 - regex(5), kstat(7D), sd(7D), kstat(9S)
217 + date(1), sh(1), time(2), clock_gettime(3C), gmatch(3GEN), kstat(3KSTAT),
218 + regex(5), kstat(7D), sd(7D), kstat(9S)
258 219
259 220 NOTES
260 - If the pattern argument contains glob or RE metacharacters which are
261 - also shell metacharacters, it will be necessary to enclose the pattern
262 - with appropriate shell quotes.
221 + If the pattern argument contains glob or RE metacharacters which are also
222 + shell metacharacters, it will be necessary to enclose the pattern with
223 + appropriate shell quotes.
263 224
264 -
265 -
266 - January 9, 2013 KSTAT(1M)
225 +illumos January 27, 2016 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX