fix cross reference (clock_gettime, not gettimeofday).
codereview and testing fixes.
6558 kstat: desire type for timestamps

*** 1,244 ****
! '\" te
  .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
! .\" 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.
! .\"  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
! .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
! .TH KSTAT 1M "Jan 9, 2013"
! .SH NAME
! kstat \- display kernel statistics
! .SH SYNOPSIS
! .LP
! .nf
! \fBkstat\fR [\fB-Cjlpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR] [\fB-m\fR \fImodule\fR]
!      [\fB-i\fR \fIinstance\fR] [\fB-n\fR \fIname\fR] [\fB-s\fR \fIstatistic\fR]
!      [interval [count]]
! .fi
! 
! .LP
! .nf
! \fBkstat\fR [\fB-Cjlpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR]
!      [\fImodule\fR[:\fIinstance\fR[:\fIname\fR[:\fIstatistic\fR]]]]...
!      [interval [count]]
! .fi
! 
! .SH DESCRIPTION
! .sp
! .LP
! The \fBkstat\fR 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.
! .sp
! .LP
  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 \fBsd\fR(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.
! .sp
! .LP
  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 \fBkstat\fR; thus, all published values can
! be referenced as \fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR.
! .sp
! .LP
  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.
! .SH OPTIONS
! .sp
! .LP
  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.
! .sp
! .LP
! The argument for the \fB-c\fR, \fB-i\fR, \fB-m\fR, \fB-n\fR, and \fB-s\fR
  options may be specified as a shell glob pattern, or a regular expression
  enclosed in '/' characters.
! .sp
! .ne 2
! .na
! \fB\fB-C\fR\fR
! .ad
! .RS 16n
  Displays output in parseable format with a colon as separator.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-c\fR \fIclass\fR\fR
! .ad
! .RS 16n
! Displays only kstats that match the specified class. \fIclass\fR is a
! kernel-defined string which classifies the "type" of the kstat.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-i\fR \fIinstance\fR\fR
! .ad
! .RS 16n
  Displays only kstats that match the specified instance.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-j\fR\fR
! .ad
! .RS 16n
  Displays output in JSON format.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-l\fR\fR
! .ad
! .RS 16n
  Lists matching kstat names without displaying values.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-m\fR \fImodule\fR\fR
! .ad
! .RS 16n
  Displays only kstats that match the specified module.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-n\fR \fIname\fR\fR
! .ad
! .RS 16n
  Displays only kstats that match the specified name.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-p\fR\fR
! .ad
! .RS 16n
  Displays output in parseable format. All example output in this document is
! given in this format. If this option is not specified, \fBkstat\fR produces
! output in a human-readable, table format.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-q\fR\fR
! .ad
! .RS 16n
  Displays no output, but return appropriate exit status for matches against
  given criteria.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-s\fR \fIstatistic\fR\fR
! .ad
! .RS 16n
  Displays only kstats that match the specified statistic.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-T\fR d | u\fR
! .ad
! .RS 16n
! Displays a time stamp before each statistics block, either in \fBdate\fR(1)
  format (\fBd\fR) or as an alphanumeric representation of the value returned by
! \fBtime\fR(2) (\fBu\fR).
! .RE
! 
! .SH OPERANDS
! .sp
! .LP
  The following operands are supported:
! .sp
! .ne 2
! .na
! \fB\fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR\fR
! .ad
! .sp .6
! .RS 4n
  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.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fIinterval\fR\fR
! .ad
! .sp .6
! .RS 4n
  The number of seconds between reports.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fIcount\fR\fR
! .ad
! .sp .6
! .RS 4n
  The number of reports to be printed.
! .RE
! 
! .SH EXAMPLES
! .sp
! .LP
  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.
! .LP
! \fBExample 1 \fRUsing the \fBkstat\fR Command
! .sp
! .in +2
! .nf
! example$ \fBkstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
  example$ \fBkstat -p -s 'avenrun*'\fR
  example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
  example$ \fBkstat -p ':::avenrun*'\fR
  example$ \fBkstat -p ':::/^avenrun_[0-9]+min$/'\fR
! 
  unix:0:system_misc:avenrun_15min        3
  unix:0:system_misc:avenrun_1min 4
  unix:0:system_misc:avenrun_5min 2
! .fi
! .in -2
! .sp
! 
! .LP
! \fBExample 2 \fRUsing the \fBkstat\fR Command
! .sp
! .in +2
! .nf
  example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
  example$ \fBkstat -p cpu_stat:::/^intr/\fR
! 
  cpu_stat:0:cpu_stat0:intr       29682330
  cpu_stat:0:cpu_stat0:intrblk    87
  cpu_stat:0:cpu_stat0:intrthread 15054222
  cpu_stat:1:cpu_stat1:intr       426073
  cpu_stat:1:cpu_stat1:intrblk    51
--- 1,209 ----
! .\" Copyright 2016 Garrett D'Amore
  .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
! .\" 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.
! .\"
! .\" 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 the fields enclosed by brackets "[]" replaced with your
! .\" own identifying information: Portions Copyright [yyyy] [name of copyright
! .\" owner]
! .\"
! .Dd Jan 27, 2016
! .Dt KSTAT 1M
! .Os
! .Sh NAME
! .Nm kstat
! .Nd display kernel statistics
! .Sh SYNOPSIS
! .Nm
! .Op Fl Cjlpq
! .Op Fl T Cm "u|d"
! .Op Fl c Ar class
! .Op Fl m Ar module
! .Op Fl i Ar instance
! .Op Fl n Ar name
! .Op Fl s Ar statistic
! .Op Fl H Cm "o|b|u|d|n|I|Z"
! .Op interval Op count
! .Nm
! .Op Fl Cjlpq
! .Op Fl T Cm "u|d"
! .Op Fl c Ar class
! .Op Fl H Cm "o|b|u|d|n|I|Z"
! .Op Ar module Ns Op ":" Ns Ar instance Ns Op ":" Ns Ar name Ns Op ":" Ns Ar statistic
! .Ar ...
! .Op interval Op count
! .
! .Sh DESCRIPTION
! The
! .Nm
! 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.
! .Lp
  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
! .Xr 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.
! .Lp
  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
! .Va kstat ;
! thus, all published values can
! be referenced as
! .Ar module Ns : Ns Ar instance Ns : Ns Ar name Ns : Ns Ar statistic Ns .
! .Lp
  When invoked without any module operands or options, kstat will match all
! defined statistics on the system. Example invocations are provided below.
! .
! .Sh 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.
! .Lp
! The argument for the
! .Fl c , i , m , n , No and Fl s
  options may be specified as a shell glob pattern, or a regular expression
  enclosed in '/' characters.
! .
! .Bl -tag -width Ds
! .It Fl C
  Displays output in parseable format with a colon as separator.
! .It Fl H Cm o|b|u|d|n|I|Z
! Displays times in the specified format, after normalizing them.
! This can be any of the following:
! .Bl -tag -width Ds
! .It Sy 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.
! .It Sy b
! Displays a fractional number of seconds since system boot.
! .It Sy u
! Displays a fractional number of seconds since the epoch (Jan 1, 1970 UTC).
! .It Sy d
! Displays in the same format as from
! .Xr date 1 .
! .It Sy n
! Displays a whole number of nanoseconds since the epoch.
! .It Sy I
! Displays an ISO 8601:2000 standard time format in the local timezone.
! .It Sy Z
! Displays an ISO 8601:2000 standard time format in UTC.
! .El
! .Lp
! Note that when using normalized time formats, the accuracy of
! the result will depend on the resolution of the realtime clock (see
! .Xr 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.
! .
! .It Fl c Ar class
! Displays only kstats that match the specified class.
! .Ar class
! is a kernel-defined string which classifies the "type" of the kstat.
! .It Fl i Ar instance
  Displays only kstats that match the specified instance.
! .It Fl j
  Displays output in JSON format.
! .It Fl l
  Lists matching kstat names without displaying values.
! .It Fl m Ar module
  Displays only kstats that match the specified module.
! .It Fl n Ar name
  Displays only kstats that match the specified name.
! .It Fl p
  Displays output in parseable format. All example output in this document is
! given in this format. If this option is not specified,
! .Nm
! produces output in a human-readable, table format.
! .It Fl q
  Displays no output, but return appropriate exit status for matches against
  given criteria.
! .It Fl s Ar statistic
  Displays only kstats that match the specified statistic.
! .It Fl T Cm "d|u"
! Displays a time stamp before each statistics block, either in
! .Xr date 1
  format (\fBd\fR) or as an alphanumeric representation of the value returned by
! .Xr time 2
! (\fBu\fR).
! .El
! .Sh OPERANDS
  The following operands are supported:
! .Bl -tag -width Ds
! .It Ar module Ns : Ns Ar instance Ns : Ns Ar name Ns : Ns Ar statistic Ns
  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.
! .It Ar interval
  The number of seconds between reports.
! .It Ar count
  The number of reports to be printed.
! .El
! .Sh FILES
! .Bl -tag -width Ds
! .It Pa /dev/kstat
! kernel statistics driver
! .El
! .Sh EXIT STATUS
! The following exit values are returned:
! .Lp
! .Bl -tag -width Ds -compact
! .It 0
! One or more statistics were matched.
! .It 1
! No statistics were matched.
! .It 2
! Invalid command line options were specified.
! .It 3
! A fatal error occurred.
! .El
! .Sh 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.
! .
! .Ss Example 1: Using the kstat Command
! .Bd -literal -offset indent
! example$ \fBlstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
  example$ \fBkstat -p -s 'avenrun*'\fR
  example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
  example$ \fBkstat -p ':::avenrun*'\fR
  example$ \fBkstat -p ':::/^avenrun_[0-9]+min$/'\fR
! .sp
  unix:0:system_misc:avenrun_15min        3
  unix:0:system_misc:avenrun_1min 4
  unix:0:system_misc:avenrun_5min 2
! .Ed
! .
! .Ss Example 2: Using the kstat Command
! .Bd -literal -offset indent
  example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
  example$ \fBkstat -p cpu_stat:::/^intr/\fR
! .sp
  cpu_stat:0:cpu_stat0:intr       29682330
  cpu_stat:0:cpu_stat0:intrblk    87
  cpu_stat:0:cpu_stat0:intrthread 15054222
  cpu_stat:1:cpu_stat1:intr       426073
  cpu_stat:1:cpu_stat1:intrblk    51
*** 247,390 ****
  cpu_stat:2:cpu_stat2:intrblk    0
  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
! .fi
! .in -2
! .sp
! 
! .LP
! \fBExample 3 \fRUsing the \fBkstat\fR Command
! .sp
! .in +2
! .nf
  example$ \fBkstat -p :::state ':::avenrun*'\fR
  example$ \fBkstat -p :::state :::/^avenrun/\fR
! 
  cpu_info:0:cpu_info0:state      on-line
  cpu_info:1:cpu_info1:state      on-line
  cpu_info:2:cpu_info2:state      on-line
  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
! .fi
! .in -2
! .sp
! 
! .LP
! \fBExample 4 \fRUsing the \fBkstat\fR Command
! .sp
! .in +2
! .nf
  example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
  unix:0:system_misc:avenrun_15min        15
  unix:0:system_misc:avenrun_1min 11
  unix:0:system_misc:avenrun_5min 21
! 
  unix:0:system_misc:avenrun_15min        15
  unix:0:system_misc:avenrun_1min 11
  unix:0:system_misc:avenrun_5min 21
! 
  unix:0:system_misc:avenrun_15min        15
  unix:0:system_misc:avenrun_1min 11
  unix:0:system_misc:avenrun_5min 21
! .fi
! .in -2
! .sp
! 
! .LP
! \fBExample 5 \fRUsing the \fBkstat\fR Command
! .sp
! .in +2
! .nf
  example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
  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
! 
  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
! .fi
! .in -2
! .sp
! 
! .LP
! \fBExample 6 \fRUsing the \fBkstat\fR Command
! .sp
! .in +2
! .nf
  example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
  932668656
  unix:0:system_misc:avenrun_15min        14
  unix:0:system_misc:avenrun_1min 5
  unix:0:system_misc:avenrun_5min 18
! .fi
! .in -2
! .sp
! 
! .SH EXIT STATUS
! .sp
! .LP
! The following exit values are returned:
! .sp
! .ne 2
! .na
! \fB\fB0\fR\fR
! .ad
! .RS 5n
! One or more statistics were matched.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB1\fR\fR
! .ad
! .RS 5n
! No statistics were matched.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB2\fR\fR
! .ad
! .RS 5n
! Invalid command line options were specified.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB3\fR\fR
! .ad
! .RS 5n
! A fatal error occurred.
! .RE
! 
! .SH FILES
! .sp
! .ne 2
! .na
! \fB\fB/dev/kstat\fR\fR
! .ad
! .RS 14n
! kernel statistics driver
! .RE
! 
! .SH SEE ALSO
! .sp
! .LP
! \fBdate\fR(1), \fBsh\fR(1), \fBtime\fR(2), \fBgmatch\fR(3GEN),
! \fBkstat\fR(3KSTAT), \fBattributes\fR(5), \fBregex\fR(5), \fBkstat\fR(7D),
! \fBsd\fR(7D), \fBkstat\fR(9S)
! .SH NOTES
! .sp
! .LP
  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.
--- 212,285 ----
  cpu_stat:2:cpu_stat2:intrblk    0
  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
! .Ed
! .
! .Ss Example 3: Using the kstat Command
! .Bd -literal -offset indent
  example$ \fBkstat -p :::state ':::avenrun*'\fR
  example$ \fBkstat -p :::state :::/^avenrun/\fR
! .sp
  cpu_info:0:cpu_info0:state      on-line
  cpu_info:1:cpu_info1:state      on-line
  cpu_info:2:cpu_info2:state      on-line
  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
! .Ed
! .
! .Ss Example 4: Using the kstat Command
! .Bd -literal -offset indent
  example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
  unix:0:system_misc:avenrun_15min        15
  unix:0:system_misc:avenrun_1min 11
  unix:0:system_misc:avenrun_5min 21
! .sp
  unix:0:system_misc:avenrun_15min        15
  unix:0:system_misc:avenrun_1min 11
  unix:0:system_misc:avenrun_5min 21
! .sp
  unix:0:system_misc:avenrun_15min        15
  unix:0:system_misc:avenrun_1min 11
  unix:0:system_misc:avenrun_5min 21
! .Ed
! .
! .Ss Example 5: Using the kstat Command
! .Bd -literal -offset indent
  example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
  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
! .sp
  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
! .Ed
! .
! .Ss Example 6: Using the kstat Command
! .Bd -literal -offset indent
  example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
  932668656
  unix:0:system_misc:avenrun_15min        14
  unix:0:system_misc:avenrun_1min 5
  unix:0:system_misc:avenrun_5min 18
! .Ed
! .Sh SEE ALSO
! .Xr date 1 ,
! .Xr sh 1 ,
! .Xr time 2 ,
! .Xr clock_gettime 3C ,
! .Xr gmatch 3GEN ,
! .Xr kstat 3KSTAT ,
! .Xr regex 5 ,
! .Xr kstat 7D ,
! .Xr sd 7D ,
! .Xr kstat 9S
! .Sh 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.