Kstat(3PERL) Perl Library Functions Kstat(3PERL)NAMEKstat - 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 ALSOperl(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)
