Manpages

Resource

NAME

SYNOPSIS

        use BSD::Resource;

        #
        # the process resource consumption so far
        #

        ($usertime, $systemtime,
         $maxrss, $ixrss, $idrss, $isrss, $minflt, $majflt, $nswap,
         $inblock, $oublock, $msgsnd, $msgrcv,
         $nsignals, $nvcsw, $nivcsw) = getrusage($ru_who);

        $rusage = getrusage($ru_who);

        #
        # the process resource limits
        #

        ($nowsoft, $nowhard) = getrlimit($resource);

        $rlimit = getrlimit($resource);

        $success = setrlimit($resource, $newsoft, $newhard);

        #
        # the process scheduling priority
        #

        $nowpriority = getpriority($pr_which, $pr_who);

        $success = setpriority($pr_which, $pr_who, $priority);

        # The following is not a BSD function.
        # It is a Perlish utility for the users of BSD::Resource.

        $rlimits = get_rlimits();

DESCRIPTION

getrusage

        ($usertime, $systemtime,
         $maxrss, $ixrss, $idrss, $isrss, $minflt, $majflt, $nswap,
         $inblock, $oublock, $msgsnd, $msgrcv,
         $nsignals, $nvcsw, $nivcsw) = getrusage($ru_who);

        $rusage = getrusage($ru_who);

        # $ru_who argument is optional; it defaults to RUSAGE_SELF

        $rusage = getrusage();

The "RUSAGE_CHILDREN" is the total sum of all the so far terminated (either successfully or unsuccessfully) child processes: there is no way to find out information about child processes still running.

On some systems (those supporting both getrusage() and the POSIX threads) there is also "RUSAGE_THREAD". The BSD::Resource supports the "RUSAGE_THREAD" if it is present but understands nothing more about the POSIX threads themselves. Similarly for "RUSAGE_BOTH": some systems support retrieving the sums of the self and child resource consumptions simultaneously.

In list context getrusage() returns the current resource usages as a list. On failure it returns an empty list.

The elements of the list are, in order:         index   name            meaning usually (quite system dependent)

         0      utime           user time
         1      stime           system time
         2      maxrss          maximum shared memory or current resident set
         3      ixrss           integral shared memory
         4      idrss           integral or current unshared data
         5      isrss           integral or current unshared stack
         6      minflt          page reclaims
         7      majflt          page faults
         8      nswap           swaps
         9      inblock         block input operations
        10      oublock         block output operations
        11      msgsnd          messages sent
        12      msgrcv          messaged received
        13      nsignals        signals received
        14      nvcsw           voluntary context switches
        15      nivcsw          involuntary context switches

        $ru = getrusage();
        print $ru->stime, "\n";

        $total_context_switches = $ru->nvcsw + $ru->nivcsw;

Note 1: officially HP-UX does not support getrusage() at all but for the time being, it does seem to.

Note 2: Because not all kernels are BSD and also because of the sloppy support of getrusage() by many vendors many of the values may not be updated.

For example Solaris 1 claims in "<sys/rusage.h>" that the "ixrss" and the "isrss" fields are always zero.

In SunOS 5.5 and 5.6 the getrusage() leaves most of the fiels zero and therefore getrusage() is not even used, instead of that the /proc interface is used. The mapping is not perfect: the maxrss field is really the current resident size instead of the maximum, the idrss is really the current heap size instead of the integral data, the isrss is really the current stack size instead of the integral stack. The ixrss has no sensible counterpart at all so it stays zero.  

getrlimit

        ($nowsoft, $nowhard) = getrlimit($resource);

        $rlimit = getrlimit($resource);

        $resource               usual meaning           usual unit

        RLIMIT_CPU              CPU time                seconds

        RLIMIT_FSIZE            file size               bytes

        RLIMIT_DATA             data size               bytes
        RLIMIT_STACK            stack size              bytes
        RLIMIT_CORE             coredump size           bytes
        RLIMIT_RSS              resident set size       bytes
        RLIMIT_MEMLOCK          memory locked data size bytes

        RLIMIT_NPROC            number of processes     1

        RLIMIT_NOFILE           number of open files    1
        RLIMIT_OFILE            number of open files    1
        RLIMIT_OPEN_MAX         number of open files    1

        RLIMIT_AS               (virtual) address space bytes
        RLIMIT_VMEM             virtual memory (space)  bytes

        RLIMIT_TCACHE           maximum number of       1
                                cached threads

        RLIMIT_AIO_MEM          maximum memory locked   bytes
                                for POSIX AIO
        RLIMIT_AIO_OPS          maximum number          1
                                for POSIX AIO ops

Two meta-resource-symbols might exist

        RLIM_NLIMITS
        RLIM_INFINITY

In list context "getrlimit()" returns the current soft and hard resource limits as a list. On failure it returns an empty list.

Processes have soft and hard resource limits. On crossing the soft limit they receive a signal (for example the "SIGXCPU" or "SIGXFSZ", corresponding to the "RLIMIT_CPU" and "RLIMIT_FSIZE", respectively). The processes can trap and handle some of these signals, please see the Signals entry in the perlipc manpage. After the hard limit the processes will be ruthlessly killed by the "KILL" signal which cannot be caught.

NOTE: the level of 'support' for a resource varies. Not all the systems

        a) even recognise all those limits
        b) really track the consumption of a resource
        c) care (send those signals) if a resource limit is exceeded

One notable exception for the better: officially HP-UX does not support getrlimit() at all but for the time being, it does seem to.

In scalar context getrlimit() returns the current soft and hard resource limits as an object. The object can be queried via methods "cur" and "max", the current and maximum resource limits for the "$resource", respectively.  

getpriority

        $nowpriority = getpriority($pr_which, $pr_who);

        # the default $pr_who is 0 (the current $pr_which)

        $nowpriority = getpriority($pr_which);

        # the default $pr_which is PRIO_PROCESS (the process priority)

        $nowpriority = getpriority();

The priorities returned by getpriority() are in the (inclusive) range "PRIO_MIN"..."PRIO_MAX". The $pr_which argument can be any of PRIO_PROCESS (a process) "PRIO_USER" (a user), or "PRIO_PGRP" (a process group). The $pr_who argument tells which process/user/process group, 0 signifying the current one.

Usual values for "PRIO_MIN", "PRIO_MAX", are -20, 20. A negative value means better priority (more impolite process), a positive value means worse priority (more polite process).

NOTE: in AIX if the BSD compatibility library is not installed or not found by the installation procedure of the BSD::Resource the "PRIO_MIN" is 0 (corresponding to -20) and "PRIO_MAX" is 39 (corresponding to 19, the BSD priority 20 is unreachable).  

setrlimit

        $success = setrlimit($resource, $newsoft, $newhard);

NOTE: A normal user process can only lower its resource limits. Soft or hard limit "RLIM_INFINITY" means as much as possible, the real hard limits are normally buried inside the kernel and are very system-dependent.  

setpriority

        $success = setpriority($pr_which, $pr_who, $priority);

        # NOTE! If there are two arguments the second one is
        # the new $priority (not $pr_who) and the $pr_who is
        # defaulted to 0 (the current $pr_which)

        $success = setpriority($pr_which, $priority);

        # The $pr_who defaults to 0 (the current $pr_which) and
        # the $priority defaults to half of the PRIO_MAX, usually
        # that amounts to 10 (being a nice $pr_which).

        $success = setpriority($pr_which);

        # The $pr_which defaults to PRIO_PROCESS,

        $success = setpriority();

NOTE: A successful call returns "1", a failed one "0".  

times

        use BSD::Resource qw(times);

        ($user, $system, $child_user, $child_system) = times();

NOTE: The current implementation uses two getrusage() system calls: one with RUSAGE_SELF and one with RUSAGE_CHILDREN. Therefore the operation is not `atomic': the times for the children are recorded a little bit later.

NOTE: times() is not imported by default by BSD::Resource.
  You need to tell that you want to use it.

NOTE: This is not a real BSD function.  

get_rlimits

        $rlimits = get_rlimits();

get_rlimits() returns a reference to hash which has the names of the available resource limits as keys and their indices (those which are needed as the first argument to getrlimit() and setrlimit()) as values. For example:

        $r = get_rlimits();
        print "ok.\n" if ($r->{'RLIM_STACK'} == RLIM_STACK);

ERRORS

*

        Your vendor has not defined BSD::Resource macro RLIMIT_...

The code tried to call getrlimit/setrlimit for a resource limit that your operating system vendor/supplier does not support. Portable code should use get_rlimits() to check which resource limits are defined.

EXAMPLES

        # the user and system times so far by the process itself

        ($usertime, $systemtime) = getrusage();

        # ditto in OO way

        $ru = getrusage();

        $usertime   = $ru->utime;
        $systemtime = $ru->stime;

        # get the current priority level of this process

        $currprio = getpriority();

VERSION

AUTHOR

Index

NAME

SYNOPSIS

DESCRIPTION

getrusage

getrlimit

getpriority

setrlimit

setpriority

times

get_rlimits

ERRORS

EXAMPLES

VERSION

AUTHOR