NAME
    Proc::Stat

SYNOPSIS
      use Proc::Stat;

      my $ps        = new Proc::Stat;
      my $psj       = $ut->jiffy();
      my $ut        = $ps->uptime();
      my $stat      = $ps->stat($pid0,$pid1,$pid...);
      my $usage     = $ut->usage($pid0,$pid1,$pid...);
      my $prep      = $ps->prepare($pid0,$pid1,...);  
      my $percent   = $prep->loadavg($pid0,$pid1,...);
      my $percent   = $ps->loadkid($pid0,$pid1,...);

DESCRIPTION
    This module reads /proc/uptime and /proc/{pid}/stat to gather statistics
    and calculate cpu utilization of designatated PID's with or without
    children

    All the data from /proc/[pid]/stat is returned attached to the method
    pointer, see list below by index (-1).

    Calculates processor JIFFY

    Calculate realtime load average of a particular job(pid) or list of
    job(pid's)

    Real load Balancing using $ps->loadavg(pid list) below.

    * $ref = new Proc::Stat;
        Return a method pointer

    * $psj = $ut->jiffy();
        Returns a blessed reference with a scalar representing the best
        guess of the SC_CLK_TCK or USR_HZ for this system based on proc data

          input:        [optional] method pointer from "uptime"
          returns:

          $psj->{
                jiffy => number
          };

        Returns 9999 on error and sets $@

        Will call $ps->uptime() if not a $ut->method pointer

        NOTE: known to be supported on LINUX, requires the /proc/filesystem

    * $ut = $ps->uptime();
          input:        none
          returns:      blessed method pointer of the form

          $ut->{        # seconds and fractions
                current => {
                        uptime  => uptime of the system,
                        idle    => time spent in idle
                },
                last    => {
                        uptime  => 0,
                        idle    => 0,
                }

          };

        Subsequent calls will return:

          $ut->{        # seconds and fractions
                current => {
                        uptime  => uptime of the system,
                        idle    => time spent in idle
                },
                last    => {
                        uptime  => previous uptime,
                        idle    => previous idle
                }
          };

        Returns undef on error

    * = $stat = $ps->stat($pid0,$pid1,...);
        Returns pointer to an array of values for each proc/PID/stat as
        defined in the man proc(5) entry elsewhere in this document

          input:        an array of PID's or ref to array of PID's
          returns:      blessed method pointer of the form

          $stat->{
                curstat => {
                        $pid0 => [stat array],
                        $pid1 => [stat array],
                        ...
                },
                lastat  => {
                        $pid0 => [],
                        $pid1 => [],
                        ...
                }
        };

        Subsequent calls will return:

          $stat->{
                curstat => {
                        $pid0 => [stat array],
                        $pid1 => [stat array],
                        ...
                },
                lastat  => {
                        $pid0 => [],
                        $pid1 => [],
                        ...
                }
        };

        Returns undef on error.

        Will not populate PID's missing from /proc

        May be chained. i.e.

          $stat = $ps->uptime()->stat($pid,...);

    * $usage = $ut->usage();
        Calculate the CPU usage from data in a chained uptime, stat call
        pair

        i.e $usage = $ps->uptime()->jiffy()->stats(pid0,pid1,...)->usage();
        in any order, only "stats" required

                calculates differences for
                        utime
                        stime
                        cutime
                        cstime

        First call for a particular PID will return the absolute value since
        job start

        Subsequent calls for a particular PID will return the difference
        from the last call

          input:        an array of PID's or ref to array of PID's
          returns:      additional fields added to "uptime" and "stats"

          $usage->{
                utime   => {
                        $pid0 => diff,
                        $pid1 => diff,
                        ...     etc...
                },
                stime   => {
                        $pid0 => diff,
                        $pid1 => diff,
                        ...     etc...
                },
                cutime  => {
                        $pid0 => diff,
                        $pid1 => diff,
                        ...     etc...
                },
                cstime  => {
                        $pid0 => diff,
                        $pid1 => diff,
                        ...     etc...
                }
          };

        Returns undef on error

    * $prep = $ps->prepare($pid0,$pid1,...);
        Collect information about jobs(pids) needed to calculate cpu
        utilization. Call repetitively at intervals.

          input:        an array of PID's or ref to array of PID's
          returns:      a blessed hash structure containing data

        This is a wrapper around:

                $ps->uptime()->stat($pids);

        ...and will conditionally call ->jiffy if it is not populated

    * $percent = $prep->loadavg($pid0,$pid1,...);
    * $percent = $prep->loadkid($pid0,$pid1,...);
        Call:

          method: loadavg for job(pid) utilization
          method: loadkid to include utilization of child processes

        Calculates the % CPU utilization of each job (pid) over the period
        between calls

          input:        an array of PID's or ref to array of PID's
          returns:      a blessed hash structure of the form:

          $ps   = {
                utilize => {
                        $pid0   => num[float 0..100] representing %,
                        $pid1   => num...,
                        ...
                },
          };

        Method will report ZERO for a job(pid) which does not have a
        previous call entry.

        Return undef on error.

        Will call the other package methods as needed to populate the '$ps'
        hash.

    * $ps = $ps->purgemissing($pid0,$pid1,...);
        Removes all PID's from the '$ps' structure not in the PID list

          input:        an array of PID's or ref to array of PID's
          returns:      bless reference stripped of all other PID's

        Returns undef on error

Contents of /proc/[pid]/stat from proc(5)
    pid %d

    (1) The process ID.

    comm %s

    (2) The filename of the executable, in parentheses. This is visible
    whether or not the executable is swapped out.

    state %c

    (3) One character from the string "RSDZTW" where R is running, S is
    sleeping in an interruptible wait, D is waiting in uninterruptible disk
    sleep, Z is zombie, T is traced or stopped (on a signal), and W is
    paging.

    ppid %d

    (4) The PID of the parent.

    pgrp %d

    (5) The process group ID of the process.

    session %d

    (6) The session ID of the process.

    tty_nr %d

    (7) The controlling terminal of the process. (The minor device number is
    contained in the combination of bits 31 to 20 and 7 to 0; the major
    device number is in bits 15 to 8.)

    tpgid %d

    (8) The ID of the foreground process group of the controlling terminal
    of the process.

    flags %u (%lu before Linux 2.6.22)

    (9) The kernel flags word of the process. For bit meanings, see the PF_*
    defines in the Linux kernel source file include/linux/sched.h. Details
    depend on the kernel version.

    minflt %lu

    (10) The number of minor faults the process has made which have not
    required loading a memory page from disk.

    cminflt %lu

    (11) The number of minor faults that the process's waited-for children
    have made.

    majflt %lu

    (12) The number of major faults the process has made which have required
    loading a memory page from disk.

    cmajflt %lu

    (13) The number of major faults that the process's waited-for children
    have made.

    utime %lu

    (14) Amount of time that this process has been scheduled in user mode,
    measured in clock ticks (divide by sysconf(_SC_CLK_TCK)). This includes
    guest time, guest_time (time spent running a virtual CPU, see below), so
    that applications that are not aware of the guest time field do not lose
    that time from their calculations.

    stime %lu

    (15) Amount of time that this process has been scheduled in kernel mode,
    measured in clock ticks (divide by sysconf(_SC_CLK_TCK)).

    cutime %ld

    (16) Amount of time that this process's waited-for children have been
    scheduled in user mode, measured in clock ticks (divide by
    sysconf(_SC_CLK_TCK)). (See also times(2).) This includes guest time,
    cguest_time (time spent running a virtual CPU, see below).

    cstime %ld

    (17) Amount of time that this process's waited-for children have been
    scheduled in kernel mode, measured in clock ticks (divide by
    sysconf(_SC_CLK_TCK)).

    priority %ld

    (18) (Explanation for Linux 2.6) For processes running a real-time
    scheduling policy (policy below; see sched_setscheduler(2)), this is the
    negated scheduling priority, minus one; that is, a number in the range
    -2 to -100, corresponding to real-time priorities 1 to 99. For processes
    running under a non-real-time scheduling policy, this is the raw nice
    value (setpriority(2)) as represented in the kernel. The kernel stores
    nice values as numbers in the range 0 (high) to 39 (low), corresponding
    to the user-visible nice range of -20 to 19.

    Before Linux 2.6, this was a scaled value based on the scheduler
    weighting given to this process.

    nice %ld

    (19) The nice value (see setpriority(2)), a value in the range 19 (low
    priority) to -20 (high priority).

    num_threads %ld

    (20) Number of threads in this process (since Linux 2.6). Before kernel
    2.6, this field was hard coded to 0 as a placeholder for an earlier
    removed field.

    itrealvalue %ld

    (21) The time in jiffies before the next SIGALRM is sent to the process
    due to an interval timer. Since kernel 2.6.17, this field is no longer
    maintained, and is hard coded as 0.

    starttime %llu (was %lu before Linux 2.6)

    (22) The time the process started after system boot. In kernels before
    Linux 2.6, this value was expressed in jiffies. Since Linux 2.6, the
    value is expressed in clock ticks (divide by sysconf(_SC_CLK_TCK)).

    vsize %lu

    (23) Virtual memory size in bytes.

    rss %ld

    (24) Resident Set Size: number of pages the process has in real memory.
    This is just the pages which count toward text, data, or stack space.
    This does not include pages which have not been demand-loaded in, or
    which are swapped out.

    rsslim %lu

    (25) Current soft limit in bytes on the rss of the process; see the
    description of RLIMIT_RSS in getrlimit(2).

    startcode %lu

    (26) The address above which program text can run.

    endcode %lu

    (27) The address below which program text can run.

    startstack %lu

    (28) The address of the start (i.e., bottom) of the stack.

    kstkesp %lu

    (29) The current value of ESP (stack pointer), as found in the kernel
    stack page for the process.

    kstkeip %lu

    (30) The current EIP (instruction pointer).

    signal %lu

    (31) The bitmap of pending signals, displayed as a decimal number.
    Obsolete, because it does not provide information on real-time signals;
    use /proc/[pid]/status instead.

    blocked %lu

    (32) The bitmap of blocked signals, displayed as a decimal number.
    Obsolete, because it does not provide information on real-time signals;
    use /proc/[pid]/status instead.

    sigignore %lu

    (33) The bitmap of ignored signals, displayed as a decimal number.
    Obsolete, because it does not provide information on real-time signals;
    use /proc/[pid]/status instead.

    sigcatch %lu

    (34) The bitmap of caught signals, displayed as a decimal number.
    Obsolete, because it does not provide information on real-time signals;
    use /proc/[pid]/status instead.

    wchan %lu

    (35) This is the "channel" in which the process is waiting. It is the
    address of a system call, and can be looked up in a namelist if you need
    a textual name. (If you have an up-to-date /etc/psdatabase, then try ps
    -l to see the WCHAN field in action.)

    nswap %lu

    (36) Number of pages swapped (not maintained).

    cnswap %lu

    (37) Cumulative nswap for child processes (not maintained).

    exit_signal %d (since Linux 2.1.22)

    (38) Signal to be sent to parent when we die.

    processor %d (since Linux 2.2.8)

    (39) CPU number last executed on.

    rt_priority %u (since Linux 2.5.19; was %lu before Linux 2.6.22)

    (40) Real-time scheduling priority, a number in the range 1 to 99 for
    processes scheduled under a real-time policy, or 0, for non-real-time
    processes (see sched_setscheduler(2)).

    policy %u (since Linux 2.5.19; was %lu before Linux 2.6.22)

    (41) Scheduling policy (see sched_setscheduler(2)). Decode using the
    SCHED_* constants in linux/sched.h.

    delayacct_blkio_ticks %llu (since Linux 2.6.18)

    (42) Aggregated block I/O delays, measured in clock ticks
    (centiseconds).

    guest_time %lu (since Linux 2.6.24)

    (43) Guest time of the process (time spent running a virtual CPU for a
    guest operating system), measured in clock ticks (divide by
    sysconf(_SC_CLK_TCK)).

    cguest_time %ld (since Linux 2.6.24)

    (44) Guest time of the process's children, measured in clock ticks
    (divide by sysconf(_SC_CLK_TCK)).

BUGS
    none so far

COPYRIGHT 2019
    Michael Robinton <michael@bizsystems.com>

    All rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either:

      a) the GNU General Public License as published by the Free
      Software Foundation; either version 2, or (at your option) any
      later version, or

      b) the "Artistic License" which comes with this distribution.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
    General Public License or the Artistic License for more details.

    You should have received a copy of the Artistic License with this
    distribution, in the file named "Artistic". If not, I'll be glad to
    provide one.

    You should also have received a copy of the GNU General Public License
    along with this program in the file named "Copying". If not, write to
    the

            Free Software Foundation, Inc.
            51 Franklin Street, Fifth Floor
            Boston, MA 02110-1301 USA.

    or visit their web page on the internet at:

            http://www.gnu.org/copyleft/gpl.html.

AUTHOR
    Michael Robinton <michael@bizsystems.com>