Kstat(3PERL)		    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 consisting of the
       module, the instance, and the statistic name. For example, CPU informa‐
       tion  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 par‐
       ticular 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 structure 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 automatically 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.

       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 additional refer‐
       ences of members of the hash, such as

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

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

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

       64-bit intervals and timThese are the crtime and snaptime fields of all
			       the statistics 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, meaning that a 32-bit value	 would
			       represent approximately 4 seconds. The alterna‐
			       tive is to store the values  as	floating-point
			       numbers,	 which	offer approximately 53 bits of
			       precision 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 precision. Accordingly,
			       all  64-bit  counters  are  stored as floating-
			       point values.

SunOS 5.10			  21 Jul 2005			  Kstat(3PERL)

Vote for polarhome