usr/src/man/man3perl/Kstat.3perl

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KSTAT 3PERL "Jul 21, 2005"
   7 .SH NAME
   8 Kstat \- Perl tied hash interface to the kstat facility
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 use Sun::Solaris::Kstat;
  13
  14 Sun::Solaris::Kstat->new();
  15 Sun::Solaris::Kstat->update();
  16 Sun::Solaris::Kstat->{module}{instance}{name}{statistic}
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 Kernel statistics are categorized using a 3-part key consisting of the module,
  23 the instance, and the statistic name. For example, CPU information can be found
  24 under \fBcpu_stat:0:cpu_stat0\fR, as in the above example. The method
  25 \fBSun::Solaris::Kstat\fR\(->\fBnew()\fR creates a new 3-layer tree of Perl
  26 hashes with the same structure; that is, the statistic for CPU 0 can be
  27 accessed as \fB$ks\(->{cpu_stat}{0}{cpu_stat0}\fR. The fourth and lowest layer
  28 is a tied hash used to hold the individual statistics values for a particular
  29 system resource.
  30 .sp
  31 .LP
  32 For performance reasons, the creation of a \fBSun::Solaris::Kstat\fR object is
  33 not accompanied by a following read of all possible statistics. Instead, the
  34 3-layer structure described above is created, but reads of a statistic's values
  35 are done only when referenced. For example, accessing
  36 \fB$ks\(->{cpu_stat}{0}{cpu_stat0}{syscall}\fR will read in all the statistics
  37 for CPU 0, including user, system, and wait times, and the other CPU
  38 statistics, as well as the number of system call entries. Once you have
  39 accessed a lowest level statistics value, calling \fB$ks\fR\(->\fBupdate()\fR
  40 will automatically update all the individual values of any statistics you have
  41 accessed.
  42 .sp
  43 .LP
  44 There are two values of the lowest-level hash that can be read without causing
  45 the full set of statistics to be read from the kernel. These are "class", which
  46 is the \fBkstat\fR class of the statistics, and "crtime"n, which is the time
  47 that the kstat was created. See \fBkstat\fR(3KSTAT) for full details of these
  48 fields.
  49 .SS "Methods"
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBnew()\fR\fR
  54 .ad
  55 .RS 12n
  56 Create a new kstat statistics hierarchy and return a reference to the top-level
  57 hash. Use it like any normal hash to access the statistics.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fBupdate()\fR\fR
  64 .ad
  65 .RS 12n
  66 Update all the statistics that have been accessed so far.  In scalar context,
  67 \fBupdate()\fR returns 1 if the \fBkstat\fR structure has changed, and 0
  68 otherwise. In list context, \fBupdate()\fR returns references to two arrays:
  69 the first holds the keys of any kstats that have been added, and the second
  70 holds the keys of any kstats that have been deleted. Each key will be returned
  71 in the form "\fBmodule\fR:\fBinstance\fR:\fBname\fR".
  72 .RE
  73
  74 .SH EXAMPLES
  75 .LP
  76 \fBExample 1 \fRSun::Solaris::Kstat example
  77 .sp
  78 .in +2
  79 .nf
  80 use Sun::Solaris::Kstat;
  81
  82 my $kstat = Sun::Solaris::Kstat->new();
  83 my ($usr1, $sys1, $wio1, $idle1) =
  84    @{$kstat->{cpu_stat}{0}{cpu_stat0}}{qw(user kernel
  85         wait idle)};
  86 print("usr sys wio idle\en");
  87 while (1) {
  88    sleep 5;
  89    if ($kstat->update()) {
  90            print("Configuration changed\en");
  91    }
  92    my ($usr2, $sys2, $wio2, $idle2) =
  93        @{$kstat->{cpu_stat}{0}{cpu_stat0}}{qw(user kernel
  94             wait idle)};
  95    printf(" %.2d  %.2d  %.2d  %.2d\en",
  96         ($usr2 - $usr1) / 5, ($sys2 - $sys1) / 5,
  97         ($wio2 - $wio1) / 5, ($idle2 - $idle1) / 5);
  98    $usr1 = $usr2;
  99    $sys1 = $sys2;
 100    $wio1 = $wio2;
 101    $idle1 = $idle2;
 102 }
 103 .fi
 104 .in -2
 105
 106 .SH SEE ALSO
 107 .sp
 108 .LP
 109 \fBperl\fR(1), \fBkstat\fR(1M), \fBkstat\fR(3KSTAT),
 110 \fBkstat_chain_update\fR(3KSTAT), \fBkstat_close\fR(3KSTAT),
 111 \fBkstat_open\fR(3KSTAT), \fBkstat_read\fR(3KSTAT)
 112 .SH NOTES
 113 .sp
 114 .LP
 115 As the statistics are stored in a tied hash, taking additional references of
 116 members of the hash, such as
 117 .sp
 118 .in +2
 119 .nf
 120 my $ref = \eks->{cpu_stat}{0}{cpu_stat0}{syscall};
 121 print("$$ref\en");
 122 .fi
 123 .in -2
 124
 125 .sp
 126 .LP
 127 will be recorded as a hold on that statistic's value, preventing it from being
 128 updated by \fBrefresh()\fR. Copy the values explicitly if persistence is
 129 necessary.
 130 .sp
 131 .LP
 132 Several of the statistics provided by the \fBkstat\fR facility are stored as
 133 64-bit integer values. Perl 5 does not yet internally support 64-bit integers,
 134 so these values are approximated in this module. There are two classes of
 135 64-bit value to be dealt with:
 136 .sp
 137 .ne 2
 138 .na
 139 \fB64-bit intervals and times\fR
 140 .ad
 141 .RS 30n
 142 These are the \fBcrtime\fR and \fBsnaptime\fR fields of all the statistics
 143 hashes, and the \fBwtime\fR, \fBwlentime\fR, \fBwlastupdate\fR, \fBrtime\fR,
 144 \fBrlentime\fR and \fBrlastupdate\fR fields of the \fBkstat\fR I/O statistics
 145 structures.  These are measured by the \fBkstat\fR facility in nanoseconds,
 146 meaning that a 32-bit value would represent approximately 4 seconds. The
 147 alternative is to store the values as floating-point numbers, which offer
 148 approximately 53 bits of  precision on present hardware. 64-bit intervals and
 149 timers as floating point values expressed in seconds, meaning that time-related
 150 kstats are being rounded to approximately microsecond resolution.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB64-bit counters\fR
 157 .ad
 158 .RS 30n
 159 It is not useful to store these values as 32-bit values. As noted above,
 160 floating-point values offer 53 bits of precision. Accordingly, all 64-bit
 161 counters are stored as floating-point values.
 162 .RE
 163