Print this page
fix cross reference (clock_gettime, not gettimeofday).
codereview and testing fixes.
6558 kstat: desire type for timestamps
@@ -1,160 +1,159 @@
KSTAT(1M) Maintenance Commands KSTAT(1M)
-
-
NAME
kstat - display kernel statistics
SYNOPSIS
- kstat [-Cjlpq] [-T u | d ] [-c class] [-m module]
- [-i instance] [-n name] [-s statistic]
- [interval [count]]
+ kstat [-Cjlpq] [-T u|d] [-c class] [-m module] [-i instance] [-n name]
+ [-s statistic] [-H o|b|u|d|n|I|Z] [interval [count]]
+ kstat [-Cjlpq] [-T u|d] [-c class] [-H o|b|u|d|n|I|Z]
+ [module[:instance[:name[:statistic]]]] ... [interval [count]]
-
- kstat [-Cjlpq] [-T u | d ] [-c class]
- [module[:instance[:name[:statistic]]]]...
- [interval [count]]
-
-
DESCRIPTION
- The kstat utility examines the available kernel statistics, or kstats,
- on the system and reports those statistics which match the criteria
+ The kstat utility examines the available kernel statistics, or kstats, on
+ the system and reports those statistics which match the criteria
specified on the command line. Each matching statistic is printed with
its module, instance, and name fields, as well as its actual value.
+ Kernel statistics may be published by various kernel subsystems, such as
+ drivers or loadable modules; each kstat has a module field that denotes
+ its publisher. Since each module might have countable entities (such as
+ multiple disks associated with the sd(7) driver) for which it wishes to
+ report statistics, the kstat also has an instance field to index the
+ statistics for each entity; kstat instances are numbered starting from
+ zero. Finally, the kstat is given a name unique within its module.
- Kernel statistics may be published by various kernel subsystems, such
- as drivers or loadable modules; each kstat has a module field that
- denotes its publisher. Since each module might have countable entities
- (such as multiple disks associated with the sd(7D) driver) for which it
- wishes to report statistics, the kstat also has an instance field to
- index the statistics for each entity; kstat instances are numbered
- starting from zero. Finally, the kstat is given a name unique within
- its module.
+ Each kstat may be a special kstat type, an array of name-value pairs, or
+ raw data. In the name-value case, each reported value is given a label,
+ which we refer to as the statistic. Known raw and special kstats are
+ given statistic labels for each of their values by kstat; thus, all
+ published values can be referenced as module:instance:name:statistic.
+ When invoked without any module operands or options, kstat will match all
+ defined statistics on the system. Example invocations are provided below.
- Each kstat may be a special kstat type, an array of name-value pairs,
- or raw data. In the name-value case, each reported value is given a
- label, which we refer to as the statistic. Known raw and special kstats
- are given statistic labels for each of their values by kstat; thus, all
- published values can be referenced as module:instance:name:statistic.
+OPTIONS
+ The tests specified by the following options are logically ANDed, and all
+ matching kstats will be selected. A regular expression containing shell
+ metacharacters must be protected from the shell by enclosing it with the
+ appropriate quotes.
+ The argument for the -c, -i, -m, -n, and -s options may be specified as a
+ shell glob pattern, or a regular expression enclosed in '/' characters.
- When invoked without any module operands or options, kstat will match
- all defined statistics on the system. Example invocations are provided
- below. All times are displayed as fractional seconds since system boot.
+ -C Displays output in parseable format with a colon as separator.
-OPTIONS
- The tests specified by the following options are logically ANDed, and
- all matching kstats will be selected. A regular expression containing
- shell metacharacters must be protected from the shell by enclosing it
- with the appropriate quotes.
+ -H o|b|u|d|n|I|Z
+ Displays times in the specified format, after normalizing them.
+ This can be any of the following:
+ o Displays snapshot and creation times as a fractional
+ number of seconds since boot, and other times as a whole
+ number of nanoseconds since boot. This the default
+ behavior.
- The argument for the -c, -i, -m, -n, and -s options may be specified as
- a shell glob pattern, or a regular expression enclosed in '/'
- characters.
+ b Displays a fractional number of seconds since system
+ boot.
- -C
- Displays output in parseable format with a colon as
- separator.
+ u Displays a fractional number of seconds since the epoch
+ (Jan 1, 1970 UTC).
+ d Displays in the same format as from date(1).
- -c class
- Displays only kstats that match the specified class.
- class is a kernel-defined string which classifies the
- "type" of the kstat.
+ n Displays a whole number of nanoseconds since the epoch.
+ I Displays an ISO 8601:2000 standard time format in the
+ local timezone.
- -i instance
- Displays only kstats that match the specified instance.
+ Z Displays an ISO 8601:2000 standard time format in UTC.
+ Note that when using normalized time formats, the accuracy of the
+ result will depend on the resolution of the realtime clock (see
+ clock_gettime(3C) ), and in no case will be more accurate to
+ absolute time than one microsecond. However, any offset error
+ between timestamps will be the same for all values displayed
+ within a single kstat snapshot.
- -j
- Displays output in JSON format.
+ -c class
+ Displays only kstats that match the specified class. class is a
+ kernel-defined string which classifies the "type" of the kstat.
+ -i instance
+ Displays only kstats that match the specified instance.
- -l
- Lists matching kstat names without displaying values.
+ -j Displays output in JSON format.
+ -l Lists matching kstat names without displaying values.
-m module
Displays only kstats that match the specified module.
-
-n name
Displays only kstats that match the specified name.
+ -p Displays output in parseable format. All example output in this
+ document is given in this format. If this option is not
+ specified, kstat produces output in a human-readable, table
+ format.
- -p
- Displays output in parseable format. All example output
- in this document is given in this format. If this
- option is not specified, kstat produces output in a
- human-readable, table format.
+ -q Displays no output, but return appropriate exit status for
+ matches against given criteria.
-
- -q
- Displays no output, but return appropriate exit status
- for matches against given criteria.
-
-
-s statistic
- Displays only kstats that match the specified
- statistic.
+ Displays only kstats that match the specified statistic.
+ -T d|u Displays a time stamp before each statistics block, either in
+ date(1) format (d) or as an alphanumeric representation of the
+ value returned by time(2) (u).
- -T d | u
- Displays a time stamp before each statistics block,
- either in date(1) format (d) or as an alphanumeric
- representation of the value returned by time(2) (u).
-
-
OPERANDS
The following operands are supported:
module:instance:name:statistic
-
Alternate method of specifying module, instance, name, and
statistic as described above. Each of the module, instance, name,
or statistic specifiers may be a shell glob pattern or a regular
expression enclosed by '/' characters. It is possible to use both
- specifier types within a single operand. Leaving a specifier empty
- is equivalent to using the '*' glob pattern for that specifier.
+ specifier types within a single operand. Leaving a specifier
+ empty is equivalent to using the '*' glob pattern for that
+ specifier.
-
interval
-
The number of seconds between reports.
+ count The number of reports to be printed.
- count
+FILES
+ /dev/kstat
+ kernel statistics driver
- The number of reports to be printed.
+EXIT STATUS
+ The following exit values are returned:
+ 0 One or more statistics were matched.
+ 1 No statistics were matched.
+ 2 Invalid command line options were specified.
+ 3 A fatal error occurred.
EXAMPLES
In the following examples, all the command lines in a block produce the
- same output, as shown immediately below. The exact statistics and
- values will of course vary from machine to machine.
+ same output, as shown immediately below. The exact statistics and values
+ will of course vary from machine to machine.
- Example 1 Using the kstat Command
-
- example$ kstat -p -m unix -i 0 -n system_misc -s 'avenrun*'
+ Example 1: Using the kstat Command
+ example$ lstat -p -m unix -i 0 -n system_misc -s 'avenrun*'
example$ kstat -p -s 'avenrun*'
example$ kstat -p 'unix:0:system_misc:avenrun*'
example$ kstat -p ':::avenrun*'
example$ kstat -p ':::/^avenrun_[0-9]+min$/'
unix:0:system_misc:avenrun_15min 3
unix:0:system_misc:avenrun_1min 4
unix:0:system_misc:avenrun_5min 2
-
-
- Example 2 Using the kstat Command
-
+ Example 2: Using the kstat Command
example$ kstat -p -m cpu_stat -s 'intr*'
example$ kstat -p cpu_stat:::/^intr/
cpu_stat:0:cpu_stat0:intr 29682330
cpu_stat:0:cpu_stat0:intrblk 87
@@ -167,14 +166,11 @@
cpu_stat:2:cpu_stat2:intrthread 131
cpu_stat:3:cpu_stat3:intr 196566
cpu_stat:3:cpu_stat3:intrblk 30
cpu_stat:3:cpu_stat3:intrthread 59626
-
-
- Example 3 Using the kstat Command
-
+ Example 3: Using the kstat Command
example$ kstat -p :::state ':::avenrun*'
example$ kstat -p :::state :::/^avenrun/
cpu_info:0:cpu_info0:state on-line
cpu_info:1:cpu_info1:state on-line
@@ -182,14 +178,11 @@
cpu_info:3:cpu_info3:state on-line
unix:0:system_misc:avenrun_15min 4
unix:0:system_misc:avenrun_1min 10
unix:0:system_misc:avenrun_5min 3
-
-
- Example 4 Using the kstat Command
-
+ Example 4: Using the kstat Command
example$ kstat -p 'unix:0:system_misc:avenrun*' 1 3
unix:0:system_misc:avenrun_15min 15
unix:0:system_misc:avenrun_1min 11
unix:0:system_misc:avenrun_5min 21
@@ -199,14 +192,11 @@
unix:0:system_misc:avenrun_15min 15
unix:0:system_misc:avenrun_1min 11
unix:0:system_misc:avenrun_5min 21
-
-
- Example 5 Using the kstat Command
-
+ Example 5: Using the kstat Command
example$ kstat -p -T d 'unix:0:system_misc:avenrun*' 5 2
Thu Jul 22 19:39:50 1999
unix:0:system_misc:avenrun_15min 12
unix:0:system_misc:avenrun_1min 0
unix:0:system_misc:avenrun_5min 11
@@ -214,53 +204,22 @@
Thu Jul 22 19:39:55 1999
unix:0:system_misc:avenrun_15min 12
unix:0:system_misc:avenrun_1min 0
unix:0:system_misc:avenrun_5min 11
-
-
- Example 6 Using the kstat Command
-
+ Example 6: Using the kstat Command
example$ kstat -p -T u 'unix:0:system_misc:avenrun*'
932668656
unix:0:system_misc:avenrun_15min 14
unix:0:system_misc:avenrun_1min 5
unix:0:system_misc:avenrun_5min 18
-
-
-EXIT STATUS
- The following exit values are returned:
-
- 0
- One or more statistics were matched.
-
-
- 1
- No statistics were matched.
-
-
- 2
- Invalid command line options were specified.
-
-
- 3
- A fatal error occurred.
-
-
-FILES
- /dev/kstat
- kernel statistics driver
-
-
SEE ALSO
- date(1), sh(1), time(2), gmatch(3GEN), kstat(3KSTAT), attributes(5),
+ date(1), sh(1), time(2), clock_gettime(3C), gmatch(3GEN), kstat(3KSTAT),
regex(5), kstat(7D), sd(7D), kstat(9S)
NOTES
- If the pattern argument contains glob or RE metacharacters which are
- also shell metacharacters, it will be necessary to enclose the pattern
- with appropriate shell quotes.
+ If the pattern argument contains glob or RE metacharacters which are also
+ shell metacharacters, it will be necessary to enclose the pattern with
+ appropriate shell quotes.
-
-
- January 9, 2013 KSTAT(1M)
+illumos January 27, 2016 illumos