== Description
  A Ruby interface for the Solaris kstat library.
   
== Prerequisites
  Solaris 8 (SunOS 2.8) or later.

== Installation
  gem install solaris-kstat

== Synopsis
  require 'solaris/kstat'
  require 'pp'
  include Solaris

  k = Kstat.new('cpu_info', 0, 'cpu_info0')
  pp k.record

  {'cpu_info'=>
    {0=>
    {'cpu_info0'=>
      {'chip_id'=>0,
       'fpu_type'=>'sparcv9',
       'device_ID'=>0,
       'cpu_type'=>'sparcv9',
       'implementation'=>'Unknown',
       'clock_MHz'=>502,
       'state_begin'=>1105974702,
       'state'=>'on-line'}}}}
   
== Class Methods
Kstat.new(module=nil, instance=-1, name=nil)
   Creates and returns a Kstat object. This does not traverse the kstat
   chain. The Kstat#record method uses the values passed to actually
   retrieve data.

   You may specify a module, an instance and a name. The module defaults to
   nil (all modules), the instance defaults to -1 (all instances) and the
   name defaults to nil (all names).
   
== Instance Methods
Kstat#record
   Returns a nested hash based on the values passed to the constructor. How
   deeply that hash is nested depends on the values passed to the constructor.
   The more specific your criterion, the less data you will receive.

== Unsupported names
  The following names will not return any meaningful value:

  * kstat_headers
  * sfmmu_global_stat
  * sfmmu_percpu_stat
   
== Known Issues
  None at this time. Please report any issues on the project page at
  https://github.com/djberg96/solaris-kstat

== Designer's Notes
  I have noticed that results from the cpu_stat module differ from the output
  of the 'kstat' command line tool. I am convinced that my code is correct and
  that there is a bug in the Solaris::Kstat Perl module. Unfortunately, the
  source for the version of the Solaris::Kstat Perl module that works on
  Solaris 8 and later is not available (the version on CPAN only works on
  Solaris 6 and 7).

  See http://tinyurl.com/karxw for more details.
   
== Acknowledgements
  Thanks go to Charlie Mills for help with the 'volatile' issue for the
  original C code.

== Future Plans
  Add snaptime and crtime information to the statistics hash.
   
== License
  Artistic 2.0

== Copyright
  (C) 2003-2015 Daniel J. Berger
  All Rights Reserved

== Contributions
  Although this library is free, please consider having your company
  setup a gittip if used by your company professionally.

  http://www.gittip.com/djberg96/
    
== Warranty
  This package is provided "as is" and without any express or
  implied warranties, including, without limitation, the implied
  warranties of merchantability and fitness for a particular purpose.
	 
== Author
  Daniel J. Berger
    
== See Also
  kstat(1M)