749 "/usr/bin/kstat" should be rewritten in C
Reviewed by: Garrett D'Amore <garrett@damore.org>
Reviewed by: Brendan Gregg <brendan.gregg@joyent.com>

          --- old/usr/src/man/man1m/kstat.1m
          +++ new/usr/src/man/man1m/kstat.1m
   1    1  '\" te
   2    2  .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
   3    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    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    5  .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6      -.TH KSTAT 1M "Mar 23, 2009"
        6 +.TH KSTAT 1M "Jan 9, 2013"
   7    7  .SH NAME
   8    8  kstat \- display kernel statistics
   9    9  .SH SYNOPSIS
  10   10  .LP
  11   11  .nf
  12      -\fBkstat\fR [\fB-lpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR] [\fB-m\fR \fImodule\fR]
       12 +\fBkstat\fR [\fB-Cjlpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR] [\fB-m\fR \fImodule\fR]
  13   13       [\fB-i\fR \fIinstance\fR] [\fB-n\fR \fIname\fR] [\fB-s\fR \fIstatistic\fR]
  14   14       [interval [count]]
  15   15  .fi
  16   16  
  17   17  .LP
  18   18  .nf
  19      -\fBkstat\fR [\fB-lpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR]
       19 +\fBkstat\fR [\fB-Cjlpq\fR] [\fB-T\fR u | d ] [\fB-c\fR \fIclass\fR]
  20   20       [\fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR]...
  21   21       [interval [count]]
  22   22  .fi
  23   23  
  24   24  .SH DESCRIPTION
  25   25  .sp
  26   26  .LP
  27   27  The \fBkstat\fR utility examines the available kernel statistics, or kstats, on
  28   28  the system and reports those statistics which match the criteria specified on
  29   29  the command line. Each matching statistic is printed with its module, instance,

  30   30  and name fields, as well as its actual value.
  31   31  .sp
  32   32  .LP
  33   33  Kernel statistics may be published by various kernel subsystems, such as
  34   34  drivers or loadable modules; each kstat has a module field that denotes its
  35   35  publisher. Since each module might have countable entities (such as multiple
  36   36  disks associated with the \fBsd\fR(7D) driver) for which it wishes to report
  37   37  statistics, the kstat also has an instance field to index the statistics for
  38   38  each entity; kstat instances are numbered starting from zero. Finally, the
  39   39  kstat is given a name unique within its module.
  40   40  .sp
  41   41  .LP
  42   42  Each kstat may be a special kstat type, an array of name-value pairs, or raw
  43   43  data. In the name-value case, each reported value is given a label, which we
  44   44  refer to as the statistic. Known raw and special kstats are given statistic
  45   45  labels for each of their values by \fBkstat\fR; thus, all published values can
  46   46  be referenced as \fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR.
  47   47  .sp
  48   48  .LP
  49   49  When invoked without any module operands or options, kstat will match all
  50   50  defined statistics on the system. Example invocations are provided below. All
  51   51  times are displayed as fractional seconds since system boot.

  52   52  .SH OPTIONS
  53   53  .sp
  54   54  .LP
  55   55  The tests specified by the following options are logically ANDed, and all
  56   56  matching kstats will be selected. A regular expression containing shell
  57   57  metacharacters must be protected from the shell by enclosing it with the
  58   58  appropriate quotes.
  59   59  .sp
  60   60  .LP
  61   61  The argument for the \fB-c\fR, \fB-i\fR, \fB-m\fR, \fB-n\fR, and \fB-s\fR
  62      -options may be specified as a shell glob pattern, or a Perl regular expression
       62 +options may be specified as a shell glob pattern, or a regular expression
  63   63  enclosed in '/' characters.
  64   64  .sp
  65   65  .ne 2
  66   66  .na
       67 +\fB\fB-C\fR\fR
       68 +.ad
       69 +.RS 16n
       70 +Displays output in parseable format with a colon as separator.
       71 +.RE
       72 +
       73 +.sp
       74 +.ne 2
       75 +.na
  67   76  \fB\fB-c\fR \fIclass\fR\fR
  68   77  .ad
  69   78  .RS 16n
  70   79  Displays only kstats that match the specified class. \fIclass\fR is a
  71   80  kernel-defined string which classifies the "type" of the kstat.
  72   81  .RE
  73   82  
  74   83  .sp
  75   84  .ne 2
  76   85  .na
  77   86  \fB\fB-i\fR \fIinstance\fR\fR
  78   87  .ad
  79   88  .RS 16n
  80   89  Displays only kstats that match the specified instance.
  81   90  .RE
  82   91  
  83   92  .sp
  84   93  .ne 2
  85   94  .na
       95 +\fB\fB-j\fR\fR
       96 +.ad
       97 +.RS 16n
       98 +Displays output in JSON format.
       99 +.RE
      100 +
      101 +.sp
      102 +.ne 2
      103 +.na
  86  104  \fB\fB-l\fR\fR
  87  105  .ad
  88  106  .RS 16n
  89  107  Lists matching kstat names without displaying values.
  90  108  .RE
  91  109  
  92  110  .sp
  93  111  .ne 2
  94  112  .na
  95  113  \fB\fB-m\fR \fImodule\fR\fR

  96  114  .ad
  97  115  .RS 16n
  98  116  Displays only kstats that match the specified module.
  99  117  .RE
 100  118  
 101  119  .sp
 102  120  .ne 2
 103  121  .na
 104  122  \fB\fB-n\fR \fIname\fR\fR
 105  123  .ad
 106  124  .RS 16n
 107  125  Displays only kstats that match the specified name.
 108  126  .RE
 109  127  
 110  128  .sp
 111  129  .ne 2
 112  130  .na
 113  131  \fB\fB-p\fR\fR
 114  132  .ad
 115  133  .RS 16n
 116  134  Displays output in parseable format. All example output in this document is
 117  135  given in this format. If this option is not specified, \fBkstat\fR produces
 118  136  output in a human-readable, table format.
 119  137  .RE
 120  138  
 121  139  .sp
 122  140  .ne 2
 123  141  .na
 124  142  \fB\fB-q\fR\fR
 125  143  .ad
 126  144  .RS 16n
 127  145  Displays no output, but return appropriate exit status for matches against
 128  146  given criteria.
 129  147  .RE
 130  148  
 131  149  .sp
 132  150  .ne 2
 133  151  .na
 134  152  \fB\fB-s\fR \fIstatistic\fR\fR
 135  153  .ad
 136  154  .RS 16n
 137  155  Displays only kstats that match the specified statistic.
 138  156  .RE
 139  157  
 140  158  .sp
 141  159  .ne 2
 142  160  .na
 143  161  \fB\fB-T\fR d | u\fR
 144  162  .ad
 145  163  .RS 16n
 146  164  Displays a time stamp before each statistics block, either in \fBdate\fR(1)
 147  165  format (\fBd\fR) or as an alphanumeric representation of the value returned by
 148  166  \fBtime\fR(2) (\fBu\fR).
 149  167  .RE
 150  168  
 151  169  .SH OPERANDS
 152  170  .sp
 153  171  .LP

 154  172  The following operands are supported:
 155  173  .sp
 156  174  .ne 2
 157  175  .na
 158  176  \fB\fImodule\fR:\fIinstance\fR:\fIname\fR:\fIstatistic\fR\fR
 159  177  .ad
 160  178  .sp .6
 161  179  .RS 4n
 162  180  Alternate method of specifying module, instance, name, and statistic as
 163  181  described above. Each of the module, instance, name, or statistic specifiers
 164      -may be a shell glob pattern or a Perl regular expression enclosed by '/'
      182 +may be a shell glob pattern or a regular expression enclosed by '/'
 165  183  characters. It is possible to use both specifier types within a single operand.
 166  184  Leaving a specifier empty is equivalent to using the '*' glob pattern for that
 167  185  specifier.
 168  186  .RE
 169  187  
 170  188  .sp
 171  189  .ne 2
 172  190  .na
 173  191  \fB\fIinterval\fR\fR
 174  192  .ad

 175  193  .sp .6
 176  194  .RS 4n
 177  195  The number of seconds between reports.
 178  196  .RE
 179  197  
 180  198  .sp
 181  199  .ne 2
 182  200  .na
 183  201  \fB\fIcount\fR\fR
 184  202  .ad
 185  203  .sp .6
 186  204  .RS 4n
 187  205  The number of reports to be printed.
 188  206  .RE
 189  207  
 190  208  .SH EXAMPLES
 191  209  .sp
 192  210  .LP
 193  211  In the following examples, all the command lines in a block produce the same
 194  212  output, as shown immediately below. The exact statistics and values will of

 195  213  course vary from machine to machine.
 196  214  .LP
 197  215  \fBExample 1 \fRUsing the \fBkstat\fR Command
 198  216  .sp
 199  217  .in +2
 200  218  .nf
 201  219  example$ \fBkstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
 202  220  example$ \fBkstat -p -s 'avenrun*'\fR
 203  221  example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
 204  222  example$ \fBkstat -p ':::avenrun*'\fR
 205      -example$ \fBkstat -p ':::/^avenrun_\ed+min$/'\fR
      223 +example$ \fBkstat -p ':::/^avenrun_[[:digit:]]+min$/'\fR
 206  224  
 207  225  unix:0:system_misc:avenrun_15min        3
 208  226  unix:0:system_misc:avenrun_1min 4
 209  227  unix:0:system_misc:avenrun_5min 2
 210  228  .fi
 211  229  .in -2
 212  230  .sp
 213  231  
 214  232  .LP
 215  233  \fBExample 2 \fRUsing the \fBkstat\fR Command

 216  234  .sp
 217  235  .in +2
 218  236  .nf
 219  237  example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
 220  238  example$ \fBkstat -p cpu_stat:::/^intr/\fR
 221  239  
 222  240  cpu_stat:0:cpu_stat0:intr       29682330
 223  241  cpu_stat:0:cpu_stat0:intrblk    87
 224  242  cpu_stat:0:cpu_stat0:intrthread 15054222
 225  243  cpu_stat:1:cpu_stat1:intr       426073
 226  244  cpu_stat:1:cpu_stat1:intrblk    51
 227  245  cpu_stat:1:cpu_stat1:intrthread 289668
 228  246  cpu_stat:2:cpu_stat2:intr       134160
 229  247  cpu_stat:2:cpu_stat2:intrblk    0
 230  248  cpu_stat:2:cpu_stat2:intrthread 131
 231  249  cpu_stat:3:cpu_stat3:intr       196566
 232  250  cpu_stat:3:cpu_stat3:intrblk    30
 233  251  cpu_stat:3:cpu_stat3:intrthread 59626
 234  252  .fi
 235  253  .in -2
 236  254  .sp
 237  255  
 238  256  .LP
 239  257  \fBExample 3 \fRUsing the \fBkstat\fR Command
 240  258  .sp
 241  259  .in +2
 242  260  .nf
 243  261  example$ \fBkstat -p :::state ':::avenrun*'\fR
 244  262  example$ \fBkstat -p :::state :::/^avenrun/\fR
 245  263  
 246  264  cpu_info:0:cpu_info0:state      on-line
 247  265  cpu_info:1:cpu_info1:state      on-line
 248  266  cpu_info:2:cpu_info2:state      on-line
 249  267  cpu_info:3:cpu_info3:state      on-line
 250  268  unix:0:system_misc:avenrun_15min        4
 251  269  unix:0:system_misc:avenrun_1min 10
 252  270  unix:0:system_misc:avenrun_5min 3
 253  271  .fi
 254  272  .in -2
 255  273  .sp
 256  274  
 257  275  .LP
 258  276  \fBExample 4 \fRUsing the \fBkstat\fR Command
 259  277  .sp
 260  278  .in +2
 261  279  .nf
 262  280  example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
 263  281  unix:0:system_misc:avenrun_15min        15
 264  282  unix:0:system_misc:avenrun_1min 11
 265  283  unix:0:system_misc:avenrun_5min 21
 266  284  
 267  285  unix:0:system_misc:avenrun_15min        15
 268  286  unix:0:system_misc:avenrun_1min 11
 269  287  unix:0:system_misc:avenrun_5min 21
 270  288  
 271  289  unix:0:system_misc:avenrun_15min        15
 272  290  unix:0:system_misc:avenrun_1min 11
 273  291  unix:0:system_misc:avenrun_5min 21
 274  292  .fi
 275  293  .in -2
 276  294  .sp
 277  295  
 278  296  .LP
 279  297  \fBExample 5 \fRUsing the \fBkstat\fR Command
 280  298  .sp
 281  299  .in +2
 282  300  .nf
 283  301  example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
 284  302  Thu Jul 22 19:39:50 1999
 285  303  unix:0:system_misc:avenrun_15min        12
 286  304  unix:0:system_misc:avenrun_1min 0
 287  305  unix:0:system_misc:avenrun_5min 11
 288  306  
 289  307  Thu Jul 22 19:39:55 1999
 290  308  unix:0:system_misc:avenrun_15min        12
 291  309  unix:0:system_misc:avenrun_1min 0
 292  310  unix:0:system_misc:avenrun_5min 11
 293  311  .fi
 294  312  .in -2
 295  313  .sp
 296  314  
 297  315  .LP
 298  316  \fBExample 6 \fRUsing the \fBkstat\fR Command
 299  317  .sp
 300  318  .in +2
 301  319  .nf
 302  320  example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
 303  321  932668656
 304  322  unix:0:system_misc:avenrun_15min        14
 305  323  unix:0:system_misc:avenrun_1min 5
 306  324  unix:0:system_misc:avenrun_5min 18
 307  325  .fi
 308  326  .in -2
 309  327  .sp
 310  328  
 311  329  .SH EXIT STATUS
 312  330  .sp
 313  331  .LP
 314  332  The following exit values are returned:
 315  333  .sp
 316  334  .ne 2
 317  335  .na
 318  336  \fB\fB0\fR\fR
 319  337  .ad
 320  338  .RS 5n
 321  339  One or more statistics were matched.
 322  340  .RE
 323  341  
 324  342  .sp
 325  343  .ne 2
 326  344  .na
 327  345  \fB\fB1\fR\fR
 328  346  .ad
 329  347  .RS 5n
 330  348  No statistics were matched.
 331  349  .RE
 332  350  
 333  351  .sp
 334  352  .ne 2
 335  353  .na
 336  354  \fB\fB2\fR\fR
 337  355  .ad
 338  356  .RS 5n
 339  357  Invalid command line options were specified.
 340  358  .RE
 341  359  
 342  360  .sp
 343  361  .ne 2
 344  362  .na
 345  363  \fB\fB3\fR\fR
 346  364  .ad
 347  365  .RS 5n
 348  366  A fatal error occurred.
 349  367  .RE
 350  368  
 351  369  .SH FILES
 352  370  .sp
 353  371  .ne 2
 354  372  .na

 355  373  \fB\fB/dev/kstat\fR\fR
 356  374  .ad
 357  375  .RS 14n
 358  376  kernel statistics driver
 359  377  .RE
 360  378  
 361  379  .SH SEE ALSO
 362  380  .sp
 363  381  .LP
 364  382  \fBdate\fR(1), \fBsh\fR(1), \fBtime\fR(2), \fBgmatch\fR(3GEN),
 365      -\fBkstat\fR(3KSTAT), \fBattributes\fR(5), \fBkstat\fR(7D), \fBsd\fR(7D),
 366      -\fBkstat\fR(9S)
      383 +\fBkstat\fR(3KSTAT), \fBattributes\fR(5), \fBregex\fR(5), \fBkstat\fR(7D),
      384 +\fBsd\fR(7D), \fBkstat\fR(9S)
 367  385  .SH NOTES
 368  386  .sp
 369  387  .LP
 370      -If the pattern argument contains glob or Perl RE metacharacters which are also
      388 +If the pattern argument contains glob or RE metacharacters which are also
 371  389  shell metacharacters, it will be necessary to enclose the pattern with
 372  390  appropriate shell quotes.
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX