@node BSD/Resource, Benchmark, B/Xref, Module List
@unnumbered BSD process resource limit and priority functions


@unnumberedsec NAME

BSD::Resource - BSD process resource limit and priority functions

@unnumberedsec SYNOPSIS

@example
use BSD::Resource;
@end example

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

@example
($nowsoft, $nowhard) = getrlimit($resource);
@end example

@example
$nowpriority = getpriority($which, $pr_ywho);
@end example

@example
$success = setrlimit($resource, $newsoft, $newhard);
@end example

@example
$success = setpriority($which, $who, $priority);
@end example

@unnumberedsec DESCRIPTION

@unnumberedsubsec getrusage

For a detailed description about the values returned by getrusage()
please consult your usual C programming documentation about
getrusage() and also the header file @code{sys/resource.h}.
The $ru_who argument is either RUSAGE_SELF (the current process) or
RUSAGE_CHILDREN (all the child processes of the current process).
On some (very few) systems (those supporting both getrusage() and the
POSIX threads) there is also RUSAGE_THREAD. The BSD::Resource supports
the _THREAD flag if it is present but understands nothing about the POSIX
threads themselves.

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

Note 2: Solaris claims in @code{sys/rusage.h} that the @code{ixrss}
and the @code{isrss} fields are always zero.

@unnumberedsubsec getrlimit

Processes have soft and hard resource limits.
At soft limit they receive a signal (XCPU or XFSZ, normally)
they can trap and handle and at hard limit they will
be ruthlessly killed by the KILL signal.
The $resource argument can be one of

@example
RLIMIT_CPU RLIMIT_FSIZE
RLIMIT_DATA RLIMIT_STACK RLIMIT_CORE RLIMIT_RSS
RLIMIT_NOFILE RLIMIT_OPEN_MAX
RLIMIT_AS RLIMIT_VMEM
@end example

The last two pairs (NO_FILE, OPEN_MAX) and (AS, VMEM) mean the same,
the former being the BSD names and the latter SVR4 names.
Two meta-resource-symbols might exist

@example
RLIM_NLIMITS
RLIM_INFINITY
@end example

NLIMITS being the number of possible (but not necessarily fully supported)
resource limits, INFINITY being useful in setrlimit().

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

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

Again, please consult your usual C programming documentation.

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

@unnumberedsubsec getpriority

The priorities returned by getpriority() are [PRIO_MIN,PRIO_MAX].
The $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.

@unnumberedsubsec setrlimit

A normal user process can only lower its resource limits.
Soft or hard limit RLIM_INFINITY means as much as possible,
the real limits are normally buried inside the kernel.

@unnumberedsubsec setpriority

The priorities handled by setpriority() are [PRIO_MIN,PRIO_MAX].
A normal user process can only lower its priority (make it more positive).

@unnumberedsec EXAMPLES

@example
# the user and system times so far by the process itself
@end example

@example
($usertime, $systemtime) = getrusage(RUSAGE_SELF);
@end example

@example
# get the current priority level of this process
@end example

@example
$currprio = getpriority(PRIO_PROCESS, 0);
@end example

@unnumberedsec VERSION

v1.0, $Id: Resource.pm,v 1.6 1995/12/18 08:32:00 jhi Exp $

@unnumberedsec AUTHOR

Jarkko Hietaniemi, @code{Jarkko.Hietaniemi@@hut.fi}

