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
       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  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
");
	 while(1) {
	    sleep 5;
	    if ($kstat->update()) {
		    print("Configuration changed
");
	    }
	    my ($usr2, $sys2, $wio2, $idle2) =
		@{$kstat->{cpu_stat}{0}{cpu_stat0}}{qw(user kernel
		     wait idle)};
	    printf(" %.2d  %.2d  %.2d  %.2d
",
		 ($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 references of members of the hash, such as

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

       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 times    These 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
				     alternative 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.11							    21 Jul 2005 						      Kstat(3PERL)