.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Resource 3"
.TH Resource 3 "2016-04-25" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BSD::Resource \- BSD process resource limit and priority functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "getrusage"
.IX Subsection "getrusage"
.Vb 4
\&        ($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();
.Ve
.PP
The \f(CW$ru_who\fR argument is either \f(CW\*(C`RUSAGE_SELF\*(C'\fR (the current process) or
\&\f(CW\*(C`RUSAGE_CHILDREN\*(C'\fR (all the child processes of the current process)
or it maybe left away in which case \f(CW\*(C`RUSAGE_SELF\*(C'\fR is used.
.PP
The \f(CW\*(C`RUSAGE_CHILDREN\*(C'\fR is the total sum of all the so far
\&\fIterminated\fR (either successfully or unsuccessfully) child processes:
there is no way to find out information about child processes still
running.
.PP
On some systems (those supporting both \fIgetrusage()\fR with the \s-1POSIX\s0
threads) there can also be \f(CW\*(C`RUSAGE_THREAD\*(C'\fR. The BSD::Resource supports
the \f(CW\*(C`RUSAGE_THREAD\*(C'\fR if it is present but understands nothing more about
the \s-1POSIX\s0 threads themselves.  Similarly for \f(CW\*(C`RUSAGE_BOTH\*(C'\fR: some systems
support retrieving the sums of the self and child resource consumptions
simultaneously.
.PP
In list context \fIgetrusage()\fR returns the current resource usages as a
list. On failure it returns an empty list.
.PP
The elements of the list are, in order:
	index	name		meaning usually (quite system dependent)
.PP
.Vb 10
\&         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
.Ve
.PP
In scalar context \fIgetrusage()\fR returns the current resource usages as a
an object. The object can be queried via methods named exactly like
the middle column, \fIname\fR, in the above table.
.PP
.Vb 2
\&        $ru = getrusage();
\&        print $ru\->stime, "\en";
\&
\&        $total_context_switches = $ru\->nvcsw + $ru\->nivcsw;
.Ve
.PP
For a detailed description about the values returned by \fIgetrusage()\fR
please consult your usual C programming documentation about
\&\fIgetrusage()\fR and also the header file \f(CW\*(C`<sys/resource.h>\*(C'\fR.
(In \fBSolaris\fR, this might be \f(CW\*(C`<sys/rusage.h>\*(C'\fR).
.PP
See also \*(L"\s-1KNOWN ISSUES\*(R"\s0.
.SS "getrlimit"
.IX Subsection "getrlimit"
.Vb 1
\&        ($nowsoft, $nowhard) = getrlimit($resource);
\&
\&        $rlimit = getrlimit($resource);
.Ve
.PP
The \f(CW$resource\fR argument can be one of
.PP
.Vb 1
\&        $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_LOCKS            number of file locks    1
\&
\&        RLIMIT_AS               (virtual) address space bytes
\&        RLIMIT_VMEM             virtual memory (space)  bytes
\&
\&        RLIMIT_PTHREAD          number of pthreads      1
\&        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
\&
\&        RLIMIT_FREEMEM          portion of the total memory
\&
\&        RLIMIT_NTHR             maximum number of       1
\&                                threads
\&
\&        RLIMIT_NPTS             maximum number of       1
\&                                pseudo\-terminals
\&
\&        RLIMIT_RSESTACK         RSE stack size          bytes
\&
\&        RLIMIT_SBSIZE           socket buffer size      bytes
\&
\&        RLIMIT_SWAP             maximum swap size       bytes
\&
\&        RLIMIT_MSGQUEUE         POSIX mq size           bytes
\&
\&        RLIMIT_RTPRIO           maximum RT priority     1
\&        RLIMIT_RTTIME           maximum RT time         microseconds
\&        RLIMIT_SIGPENDING       pending signals         1
.Ve
.PP
\&\fBWhat limits are available depends on the operating system\fR.
.PP
See below for \f(CW\*(C`get_rlimits()\*(C'\fR on how to find out which limits are
available, for the exact documentation consult the documentation of
your operating system (setrlimit documentation, usually).
.PP
The two groups (\f(CW\*(C`NOFILE\*(C'\fR, \f(CW\*(C`OFILE\*(C'\fR, \f(CW\*(C`OPEN_MAX\*(C'\fR) and (\f(CW\*(C`AS\*(C'\fR, \f(CW\*(C`VMEM\*(C'\fR)
are aliases within themselves.
.PP
Two meta-resource-symbols might exist
.PP
.Vb 2
\&        RLIM_NLIMITS
\&        RLIM_INFINITY
.Ve
.PP
\&\f(CW\*(C`RLIM_NLIMITS\*(C'\fR being the number of possible (but not necessarily fully
supported) resource limits, see also the \fIget_rlimits()\fR call below.
\&\f(CW\*(C`RLIM_INFINITY\*(C'\fR is useful in \fIsetrlimit()\fR, the \f(CW\*(C`RLIM_INFINITY\*(C'\fR is
often represented as minus one (\-1).
.PP
In list context \f(CW\*(C`getrlimit()\*(C'\fR returns the current soft and hard
resource limits as a list.  On failure it returns an empty list.
.PP
Processes have soft and hard resource limits.  On crossing the soft
limit they receive a signal (for example the \f(CW\*(C`SIGXCPU\*(C'\fR or \f(CW\*(C`SIGXFSZ\*(C'\fR,
corresponding to the \f(CW\*(C`RLIMIT_CPU\*(C'\fR and \f(CW\*(C`RLIMIT_FSIZE\*(C'\fR, respectively).
The processes can trap and handle some of these signals, please see
\&\*(L"Signals\*(R" in perlipc.  After the hard limit the processes will be
ruthlessly killed by the \f(CW\*(C`KILL\*(C'\fR signal which cannot be caught.
.PP
\&\fB\s-1NOTE\s0\fR: the level of 'support' for a resource varies. Not all the systems
.PP
.Vb 3
\&        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
.Ve
.PP
Again, please consult your usual C programming documentation.
.PP
One notable exception for the better: officially \fBHP-UX\fR does not
support \fIgetrlimit()\fR at all but for the time being, it does seem to.
.PP
In scalar context \f(CW\*(C`getrlimit()\*(C'\fR returns the current soft limit.
On failure it returns \f(CW\*(C`undef\*(C'\fR.
.SS "getpriority"
.IX Subsection "getpriority"
.Vb 2
\&        # $pr_which can be PRIO_USER, PRIO_PROCESS, or PRIO_PGRP,
\&        # and in some systems PRIO_THREAD
\&
\&        $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();
.Ve
.PP
\&\fIgetpriority()\fR returns the current priority. \fB\s-1NOTE\s0\fR: \fIgetpriority()\fR
can return zero or negative values completely legally. On failure
\&\fIgetpriority()\fR returns \f(CW\*(C`undef\*(C'\fR (and \f(CW$!\fR is set as usual).
.PP
The priorities returned by \fIgetpriority()\fR are in the (inclusive) range
\&\f(CW\*(C`PRIO_MIN\*(C'\fR...\f(CW\*(C`PRIO_MAX\*(C'\fR.  The \f(CW$pr_which\fR argument can be any of
\&\s-1PRIO_PROCESS \s0(a process) \f(CW\*(C`PRIO_USER\*(C'\fR (a user), or \f(CW\*(C`PRIO_PGRP\*(C'\fR (a
process group). The \f(CW$pr_who\fR argument tells which process/user/process
group, 0 signifying the current one.
.PP
Usual values for \f(CW\*(C`PRIO_MIN\*(C'\fR, \f(CW\*(C`PRIO_MAX\*(C'\fR, are \-20, 20.  A negative
value means better priority (more impolite process), a positive value
means worse priority (more polite process).
.SS "setrlimit"
.IX Subsection "setrlimit"
.Vb 1
\&        $success = setrlimit($resource, $newsoft, $newhard);
.Ve
.PP
\&\fIsetrlimit()\fR returns true on success and \f(CW\*(C`undef\*(C'\fR on failure.
.PP
\&\fB\s-1NOTE\s0\fR: A normal user process can only lower its resource limits.
Soft or hard limit \f(CW\*(C`RLIM_INFINITY\*(C'\fR means as much as possible, the
real hard limits are normally buried inside the kernel and are \fBvery\fR
system-dependent.
.PP
\&\fB\s-1NOTE\s0\fR: Even the soft limit that is actually set might be lower than
what requested for various reasons.  One possibility is that the
actual limit on a resource might be controlled by some system variable
(e.g. in \s-1BSD\s0 systems the \s-1RLIMIT_NPROC\s0 can be capped by the system
variable \f(CW\*(C`maxprocperuid\*(C'\fR, try \f(CW\*(C`sysctl \-a kern.maxprocperuid\*(C'\fR),
or in many environments core dumping has been disabled from normal
user processes.  Another possibility is that a limit is rounded down
to some alignment or granularity, for example the memory limits might
be rounded down to the closest 4 kilobyte boundary.  In other words,
do not expect to be able to \fIsetrlimit()\fR a limit to a value and then be
able to read back the same value with \fIgetrlimit()\fR.
.SS "setpriority"
.IX Subsection "setpriority"
.Vb 1
\&        $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();
.Ve
.PP
\&\fIsetpriority()\fR is used to change the scheduling priority.  A positive
priority means a more polite process/process group/user; a negative
priority means a more impolite process/process group/user.
The priorities handled by \fIsetpriority()\fR are [\f(CW\*(C`PRIO_MIN\*(C'\fR,\f(CW\*(C`PRIO_MAX\*(C'\fR].
A normal user process can only lower its priority (make it more positive).
.PP
\&\fB\s-1NOTE\s0\fR: A successful call returns \f(CW1\fR, a failed one \f(CW0\fR.
.PP
See also \*(L"\s-1KNOWN ISSUES\*(R"\s0.
.SS "times"
.IX Subsection "times"
.Vb 1
\&        use BSD::Resource qw(times);
\&
\&        ($user, $system, $child_user, $child_system) = times();
.Ve
.PP
The BSD::Resource module offers a \fItimes()\fR implementation that has
usually slightly better time granularity than the \fItimes()\fR by Perl
core.  The time granularity of the latter is usually 1/60 seconds
while the former may achieve submilliseconds.
.PP
\&\fB\s-1NOTE\s0\fR: The current implementation uses two \fIgetrusage()\fR system calls:
one with \s-1RUSAGE_SELF\s0 and one with \s-1RUSAGE_CHILDREN. \s0 Therefore the
operation is not `atomic': the times for the children are recorded
a little bit later.
.PP
\&\fB\s-1NOTE\s0\fR: \fItimes()\fR is not imported by default by BSD::Resource.
You need to tell that you want to use it.
.PP
\&\fB\s-1NOTE:\s0 \f(BItimes()\fB is not a \*(L"real \s-1BSD\*(R"\s0 function.  It is older \s-1UNIX.\s0\fR
.SS "get_rlimits"
.IX Subsection "get_rlimits"
.Vb 2
\&        use BSD::Resource qw{get_rlimits};
\&        my $limits = get_rlimits();
.Ve
.PP
\&\fB\s-1NOTE:\s0 This is not a real \s-1BSD\s0 function. It is a convenience function
introduced by BSD::Resource.\fR
.PP
\&\fIget_rlimits()\fR 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 \fIgetrlimit()\fR and \fIsetrlimit()\fR)
as values. For example:
.PP
.Vb 6
\&        use BSD::Resource qw{get_rlimits};
\&        my $limits = get_rlimits();
\&        for my $name (keys %$limits) {
\&          my ($soft, $hard) = BSD::Resource::getrlimit($limits\->{$name});
\&          print "$name soft $soft hard $hard\en";
\&        }
.Ve
.PP
Note that a limit of \-1 means unlimited.
.SH "ERRORS"
.IX Header "ERRORS"
.IP "\(bu" 4

.Sp
.Vb 1
\&        Your vendor has not defined BSD::Resource macro ...
.Ve
.Sp
The code tried to call getrlimit/setrlimit for a resource limit that
your operating system vendor/supplier does not support.  Portable code
should use \fIget_rlimits()\fR to check which resource limits are defined.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\&        # 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();
.Ve
.SH "KNOWN ISSUES"
.IX Header "KNOWN ISSUES"
In \fB\s-1AIX\s0\fR (at least version 3, maybe later also releases) if the \s-1BSD\s0
compatibility library is not installed or not found by the BSD::Resource
installation procedure and when using the \fIgetpriority()\fR or \fIsetpriority()\fR,
the \f(CW\*(C`PRIO_MIN\*(C'\fR is 0 (corresponding to \-20) and \f(CW\*(C`PRIO_MAX\*(C'\fR is 39
(corresponding to 19, the \s-1BSD\s0 priority 20 is unreachable).
.PP
In \fBHP-UX\fR the \fIgetrusage()\fR is not Officially Supported at all but for
the time being, it does seem to be.
.PP
In \fBMac \s-1OS X\s0\fR a normal user cannot raise the \f(CW\*(C`RLIM_NPROC\*(C'\fR over the
maxprocperuid limit (the default value is 266, try the command
\&\f(CW\*(C`sysctl \-a kern.maxprocperuid\*(C'\fR).
.PP
In \fBNetBSD\fR \f(CW\*(C`RLIMIT_STACK\*(C'\fR \fIsetrlimit()\fR calls fail.
.PP
In \fBCygwin\fR \f(CW\*(C`RLIMIT_STACK\*(C'\fR setrlimit calls fail.  Also, \fIsetrlimit()\fR
\&\f(CW\*(C`RLIMIT_NOFILE/RLIMIT_OFILE/RLIMIT_OFILE\*(C'\fR calls return success, but
then the subsequent getrlimit calls show that the limits didn't really
change.
.PP
Because not all \s-1UNIX\s0 kernels are \s-1BSD\s0 and also because of the sloppy
support of \fIgetrusage()\fR by many vendors many of the \fIgetrusage()\fR values
may not be correctly updated.  For example \fBSolaris 1\fR claims in
\&\f(CW\*(C`<sys/rusage.h>\*(C'\fR that the \f(CW\*(C`ixrss\*(C'\fR and the \f(CW\*(C`isrss\*(C'\fR fields
are always zero.  In \fBSunOS 5.5 and 5.6\fR the \fIgetrusage()\fR leaves most
of the fields zero and therefore \fIgetrusage()\fR is not even used, instead
of that the \fB/proc\fR interface is used.  The mapping is not perfect:
the \f(CW\*(C`maxrss\*(C'\fR field is really the \fBcurrent\fR resident size instead of the
maximum, the \f(CW\*(C`idrss\*(C'\fR is really the \fBcurrent\fR heap size instead of the
integral data, and the \f(CW\*(C`isrss\*(C'\fR is really the \fBcurrent\fR stack size
instead of the integral stack.  The ixrss has no sensible counterpart
at all so it stays zero.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 1995\-2016 Jarkko Hietaniemi All Rights Reserved
.PP
This module free software; you can redistribute it and/or modify it
under the terms of the Artistic License 2.0 or \s-1GNU\s0 Lesser General
Public License 2.0.  For more details, see the full text of the
licenses at <http://www.perlfoundation.org/artistic_license_2_0>,
and <http://www.gnu.org/licenses/gpl\-2.0.html>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jarkko Hietaniemi, \f(CW\*(C`jhi@iki.fi\*(C'\fR