Manual Pages for UNIX Operating System command usage for man Kstat

Perl Library Functions                               Kstat(3PERL)



NAME
     Kstat - Perl tied hash interface to the kstat facility

SYNOPSIS
     use Sun::Solaris::Kstat;

     Sun::Solaris::Kstat->new();
     Sun::Solaris::Kstat->update();
     Sun::Solaris::Kstat->{module}{instance}{name}{statistic}


DESCRIPTION
     Kernel statistics are categorized using a  3-part  key  con-
     sisting of the module, the instance, and the statistic name.
     For  example,   CPU   information   can   be   found   under
     cpu_stat:0:cpu_stat0,  as  in  the above example. The method
     Sun::Solaris::Kstat->new() creates a  new  3-layer  tree  of
     Perl  hashes with the same structure; that is, the statistic
     for CPU 0 can be accessed as  $ks->{cpu_stat}{0}{cpu_stat0}.
     The  fourth and lowest layer is a tied hash used to hold the
     individual  statistics  values  for  a   particular   system
     resource.


     For    performance    reasons,    the    creation    of    a
     Sun::Solaris::Kstat object is not accompanied by a following
     read of all possible statistics. Instead, the 3-layer struc-
     ture  described above is created, but reads of a statistic's
     values are done only when referenced. For example, accessing
     $ks->{cpu_stat}{0}{cpu_stat0}{syscall}  will read in all the
     statistics for CPU  0,  including  user,  system,  and  wait
     times,  and  the other CPU statistics, as well as the number
     of system call entries. Once  you  have  accessed  a  lowest
     level statistics value, calling $ks->update() will automati-
     cally update all the individual values of any statistics you
     have accessed.


     There are two values of the lowest-level hash  that  can  be
     read  without  causing the full set of statistics to be read
     from the kernel. These are "class", which is the kstat class
     of the statistics, and "crtime"n, which is the time that the
     kstat was created. See kstat(3KSTAT)  for  full  details  of
     these fields.

  Methods
     new()       Create a  new  kstat  statistics  hierarchy  and
                 return a reference to the top-level hash. Use it
                 like any normal hash to access the statistics.






SunOS 5.11          Last change: 21 Jul 2005                    1






Perl Library Functions                               Kstat(3PERL)



     update()    Update  all  the  statistics  that   have   been
                 accessed  so  far.   In scalar context, update()
                 returns 1 if the kstat  structure  has  changed,
                 and  0  otherwise.  In  list  context,  update()
                 returns references  to  two  arrays:  the  first
                 holds  the  keys  of  any  kstats that have been
                 added, and the second  holds  the  keys  of  any
                 kstats  that have been deleted. Each key will be
                 returned in the form "module:instance:name".


EXAMPLES
     Example 1 Sun::Solaris::Kstat example

       use Sun::Solaris::Kstat;

       my $kstat = Sun::Solaris::Kstat->new();
       my ($usr1, $sys1, $wio1, $idle1) =
          @{$kstat->{cpu_stat}{0}{cpu_stat0}}{qw(user kernel
               wait idle)};
       print("usr sys wio idle\n");
       while (1) {
          sleep 5;
          if ($kstat->update()) {
                  print("Configuration changed\n");
          }
          my ($usr2, $sys2, $wio2, $idle2) =
              @{$kstat->{cpu_stat}{0}{cpu_stat0}}{qw(user kernel
                   wait idle)};
          printf(" %.2d  %.2d  %.2d  %.2d\n",
               ($usr2 - $usr1) / 5, ($sys2 - $sys1) / 5,
               ($wio2 - $wio1) / 5, ($idle2 - $idle1) / 5);
          $usr1 = $usr2;
          $sys1 = $sys2;
          $wio1 = $wio2;
          $idle1 = $idle2;
       }


SEE ALSO
     perl(1),              kstat(1M),              kstat(3KSTAT),
     kstat_chain_update(3KSTAT),             kstat_close(3KSTAT),
     kstat_open(3KSTAT), kstat_read(3KSTAT)

NOTES
     As the statistics are stored in a tied  hash,  taking  addi-
     tional references of members of the hash, such as

       my $ref = \ks->{cpu_stat}{0}{cpu_stat0}{syscall};
       print("$$ref\n");





SunOS 5.11          Last change: 21 Jul 2005                    2






Perl Library Functions                               Kstat(3PERL)



     will be recorded  as  a  hold  on  that  statistic's  value,
     preventing  it  from  being  updated  by refresh(). Copy the
     values explicitly if persistence is necessary.


     Several of the statistics provided by the kstat facility are
     stored  as 64-bit integer values. Perl 5 does not yet inter-
     nally support 64-bit integers, so these values are  approxi-
     mated  in this module. There are two classes of 64-bit value
     to be dealt with:

     64-bit intervals and times    These are the crtime and snap-
                                   time fields of all the statis-
                                   tics hashes,  and  the  wtime,
                                   wlentime,  wlastupdate, rtime,
                                   rlentime    and    rlastupdate
                                   fields   of   the   kstat  I/O
                                   statistics structures.   These
                                   are   measured  by  the  kstat
                                   facility in nanoseconds, mean-
                                   ing  that a 32-bit value would
                                   represent   approximately    4
                                   seconds. The alternative is to
                                   store the values as  floating-
                                   point   numbers,  which  offer
                                   approximately 53 bits of  pre-
                                   cision  on  present  hardware.
                                   64-bit intervals and timers as
                                   floating      point     values
                                   expressed in seconds,  meaning
                                   that  time-related  kstats are
                                   being rounded to approximately
                                   microsecond resolution.


     64-bit counters               It  is  not  useful  to  store
                                   these values as 32-bit values.
                                   As noted above, floating-point
                                   values offer 53 bits of preci-
                                   sion. Accordingly, all  64-bit
                                   counters    are    stored   as
                                   floating-point values.













SunOS 5.11          Last change: 21 Jul 2005                    3