1Resource(3)           User Contributed Perl Documentation          Resource(3)
2
3
4

NAME

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

SYNOPSIS

9               use BSD::Resource;
10
11               #
12               # the process resource consumption so far
13               #
14
15               ($usertime, $systemtime,
16                $maxrss, $ixrss, $idrss, $isrss, $minflt, $majflt, $nswap,
17                $inblock, $oublock, $msgsnd, $msgrcv,
18                $nsignals, $nvcsw, $nivcsw) = getrusage($ru_who);
19
20               $rusage = getrusage($ru_who);
21
22               #
23               # the process resource limits
24               #
25
26               ($nowsoft, $nowhard) = getrlimit($resource);
27
28               $rlimit = getrlimit($resource);
29
30               $success = setrlimit($resource, $newsoft, $newhard);
31
32               #
33               # the process scheduling priority
34               #
35
36               $nowpriority = getpriority($pr_which, $pr_who);
37
38               $success = setpriority($pr_which, $pr_who, $priority);
39
40               # The following is not a BSD function.
41               # It is a Perlish utility for the users of BSD::Resource.
42
43               $rlimits = get_rlimits();
44

DESCRIPTION

46   getrusage
47               ($usertime, $systemtime,
48                $maxrss, $ixrss, $idrss, $isrss, $minflt, $majflt, $nswap,
49                $inblock, $oublock, $msgsnd, $msgrcv,
50                $nsignals, $nvcsw, $nivcsw) = getrusage($ru_who);
51
52               $rusage = getrusage($ru_who);
53
54               # $ru_who argument is optional; it defaults to RUSAGE_SELF
55
56               $rusage = getrusage();
57
58       The $ru_who argument is either "RUSAGE_SELF" (the current process) or
59       "RUSAGE_CHILDREN" (all the child processes of the current process) or
60       it maybe left away in which case "RUSAGE_SELF" is used.
61
62       The "RUSAGE_CHILDREN" is the total sum of all the so far terminated
63       (either successfully or unsuccessfully) child processes: there is no
64       way to find out information about child processes still running.
65
66       On some systems (those supporting both getrusage() with the POSIX
67       threads) there can also be "RUSAGE_THREAD". The BSD::Resource supports
68       the "RUSAGE_THREAD" if it is present but understands nothing more about
69       the POSIX threads themselves.  Similarly for "RUSAGE_BOTH": some
70       systems support retrieving the sums of the self and child resource
71       consumptions simultaneously.
72
73       In list context getrusage() returns the current resource usages as a
74       list. On failure it returns an empty list.
75
76       The elements of the list are, in order:
77            index     name      meaning usually (quite system dependent)
78
79                0      utime           user time
80                1      stime           system time
81                2      maxrss          maximum shared memory or current resident set
82                3      ixrss           integral shared memory
83                4      idrss           integral or current unshared data
84                5      isrss           integral or current unshared stack
85                6      minflt          page reclaims
86                7      majflt          page faults
87                8      nswap           swaps
88                9      inblock         block input operations
89               10      oublock         block output operations
90               11      msgsnd          messages sent
91               12      msgrcv          messaged received
92               13      nsignals        signals received
93               14      nvcsw           voluntary context switches
94               15      nivcsw          involuntary context switches
95
96       In scalar context getrusage() returns the current resource usages as a
97       an object. The object can be queried via methods named exactly like the
98       middle column, name, in the above table.
99
100               $ru = getrusage();
101               print $ru->stime, "\n";
102
103               $total_context_switches = $ru->nvcsw + $ru->nivcsw;
104
105       For a detailed description about the values returned by getrusage()
106       please consult your usual C programming documentation about getrusage()
107       and also the header file "<sys/resource.h>".  (In Solaris, this might
108       be "<sys/rusage.h>").
109
110       See also "KNOWN ISSUES".
111
112   getrlimit
113               ($nowsoft, $nowhard) = getrlimit($resource);
114
115               $rlimit = getrlimit($resource);
116
117       The $resource argument can be one of
118
119               $resource               usual meaning           usual unit
120
121               RLIMIT_CPU              CPU time                seconds
122
123               RLIMIT_FSIZE            file size               bytes
124
125               RLIMIT_DATA             data size               bytes
126               RLIMIT_STACK            stack size              bytes
127               RLIMIT_CORE             coredump size           bytes
128               RLIMIT_RSS              resident set size       bytes
129               RLIMIT_MEMLOCK          memory locked data size bytes
130
131               RLIMIT_NPROC            number of processes     1
132
133               RLIMIT_NOFILE           number of open files    1
134               RLIMIT_OFILE            number of open files    1
135               RLIMIT_OPEN_MAX         number of open files    1
136
137               RLIMIT_LOCKS            number of file locks    1
138
139               RLIMIT_AS               (virtual) address space bytes
140               RLIMIT_VMEM             virtual memory (space)  bytes
141
142               RLIMIT_PTHREAD          number of pthreads      1
143               RLIMIT_TCACHE           maximum number of       1
144                                       cached threads
145
146               RLIMIT_AIO_MEM          maximum memory locked   bytes
147                                       for POSIX AIO
148               RLIMIT_AIO_OPS          maximum number          1
149                                       for POSIX AIO ops
150
151               RLIMIT_FREEMEM          portion of the total memory
152
153               RLIMIT_NTHR             maximum number of       1
154                                       threads
155
156               RLIMIT_NPTS             maximum number of       1
157                                       pseudo-terminals
158
159               RLIMIT_RSESTACK         RSE stack size          bytes
160
161               RLIMIT_SBSIZE           socket buffer size      bytes
162
163               RLIMIT_SWAP             maximum swap size       bytes
164
165               RLIMIT_MSGQUEUE         POSIX mq size           bytes
166
167               RLIMIT_RTPRIO           maximum RT priority     1
168               RLIMIT_RTTIME           maximum RT time         microseconds
169               RLIMIT_SIGPENDING       pending signals         1
170
171       What limits are available depends on the operating system.
172
173       See below for "get_rlimits()" on how to find out which limits are
174       available, for the exact documentation consult the documentation of
175       your operating system (setrlimit documentation, usually).
176
177       The two groups ("NOFILE", "OFILE", "OPEN_MAX") and ("AS", "VMEM") are
178       aliases within themselves.
179
180       Two meta-resource-symbols might exist
181
182               RLIM_NLIMITS
183               RLIM_INFINITY
184
185       "RLIM_NLIMITS" being the number of possible (but not necessarily fully
186       supported) resource limits, see also the get_rlimits() call below.
187       "RLIM_INFINITY" is useful in setrlimit(), the "RLIM_INFINITY" is often
188       represented as minus one (-1).
189
190       In list context "getrlimit()" returns the current soft and hard
191       resource limits as a list.  On failure it returns an empty list.
192
193       Processes have soft and hard resource limits.  On crossing the soft
194       limit they receive a signal (for example the "SIGXCPU" or "SIGXFSZ",
195       corresponding to the "RLIMIT_CPU" and "RLIMIT_FSIZE", respectively).
196       The processes can trap and handle some of these signals, please see
197       "Signals" in perlipc.  After the hard limit the processes will be
198       ruthlessly killed by the "KILL" signal which cannot be caught.
199
200       NOTE: the level of 'support' for a resource varies. Not all the systems
201
202               a) even recognise all those limits
203               b) really track the consumption of a resource
204               c) care (send those signals) if a resource limit is exceeded
205
206       Again, please consult your usual C programming documentation.
207
208       One notable exception for the better: officially HP-UX does not support
209       getrlimit() at all but for the time being, it does seem to.
210
211       In scalar context "getrlimit()" returns the current soft limit.  On
212       failure it returns "undef".
213
214   getpriority
215               # $pr_which can be PRIO_USER, PRIO_PROCESS, or PRIO_PGRP,
216               # and in some systems PRIO_THREAD
217
218               $nowpriority = getpriority($pr_which, $pr_who);
219
220               # the default $pr_who is 0 (the current $pr_which)
221
222               $nowpriority = getpriority($pr_which);
223
224               # the default $pr_which is PRIO_PROCESS (the process priority)
225
226               $nowpriority = getpriority();
227
228       getpriority() returns the current priority. NOTE: getpriority() can
229       return zero or negative values completely legally. On failure
230       getpriority() returns "undef" (and $! is set as usual).
231
232       The priorities returned by getpriority() are in the (inclusive) range
233       "PRIO_MIN"..."PRIO_MAX".  The $pr_which argument can be any of
234       PRIO_PROCESS (a process) "PRIO_USER" (a user), or "PRIO_PGRP" (a
235       process group). The $pr_who argument tells which process/user/process
236       group, 0 signifying the current one.
237
238       Usual values for "PRIO_MIN", "PRIO_MAX", are -20, 20.  A negative value
239       means better priority (more impolite process), a positive value means
240       worse priority (more polite process).
241
242   setrlimit
243               $success = setrlimit($resource, $newsoft, $newhard);
244
245       setrlimit() returns true on success and "undef" on failure.
246
247       NOTE: A normal user process can only lower its resource limits.  Soft
248       or hard limit "RLIM_INFINITY" means as much as possible, the real hard
249       limits are normally buried inside the kernel and are very system-
250       dependent.
251
252       NOTE: Even the soft limit that is actually set might be lower than what
253       requested for various reasons.  One possibility is that the actual
254       limit on a resource might be controlled by some system variable (e.g.
255       in BSD systems the RLIMIT_NPROC can be capped by the system variable
256       "maxprocperuid", try "sysctl -a kern.maxprocperuid"), or in many
257       environments core dumping has been disabled from normal user processes.
258       Another possibility is that a limit is rounded down to some alignment
259       or granularity, for example the memory limits might be rounded down to
260       the closest 4 kilobyte boundary.  In other words, do not expect to be
261       able to setrlimit() a limit to a value and then be able to read back
262       the same value with getrlimit().
263
264   setpriority
265               $success = setpriority($pr_which, $pr_who, $priority);
266
267               # NOTE! If there are two arguments the second one is
268               # the new $priority (not $pr_who) and the $pr_who is
269               # defaulted to 0 (the current $pr_which)
270
271               $success = setpriority($pr_which, $priority);
272
273               # The $pr_who defaults to 0 (the current $pr_which) and
274               # the $priority defaults to half of the PRIO_MAX, usually
275               # that amounts to 10 (being a nice $pr_which).
276
277               $success = setpriority($pr_which);
278
279               # The $pr_which defaults to PRIO_PROCESS.
280
281               $success = setpriority();
282
283       setpriority() is used to change the scheduling priority.  A positive
284       priority means a more polite process/process group/user; a negative
285       priority means a more impolite process/process group/user.  The
286       priorities handled by setpriority() are ["PRIO_MIN","PRIO_MAX"].  A
287       normal user process can only lower its priority (make it more
288       positive).
289
290       NOTE: A successful call returns 1, a failed one 0.
291
292       See also "KNOWN ISSUES".
293
294   times
295               use BSD::Resource qw(times);
296
297               ($user, $system, $child_user, $child_system) = times();
298
299       The BSD::Resource module offers a times() implementation that has
300       usually slightly better time granularity than the times() by Perl core.
301       The time granularity of the latter is usually 1/60 seconds while the
302       former may achieve submilliseconds.
303
304       NOTE: The current implementation uses two getrusage() system calls: one
305       with RUSAGE_SELF and one with RUSAGE_CHILDREN.  Therefore the operation
306       is not `atomic': the times for the children are recorded a little bit
307       later.
308
309       NOTE: times() is not imported by default by BSD::Resource.  You need to
310       tell that you want to use it.
311
312       NOTE: times() is not a "real BSD" function.  It is older UNIX.
313
314   get_rlimits
315               use BSD::Resource qw{get_rlimits};
316               my $limits = get_rlimits();
317
318       NOTE: This is not a real BSD function. It is a convenience function
319       introduced by BSD::Resource.
320
321       get_rlimits() returns a reference to hash which has the names of the
322       available resource limits as keys and their indices (those which are
323       needed as the first argument to getrlimit() and setrlimit()) as values.
324       For example:
325
326               use BSD::Resource qw{get_rlimits};
327               my $limits = get_rlimits();
328               for my $name (keys %$limits) {
329                 my ($soft, $hard) = BSD::Resource::getrlimit($limits->{$name});
330                 print "$name soft $soft hard $hard\n";
331               }
332
333       Note that a limit of -1 means unlimited.
334

ERRORS

336
337
338
339                   Your vendor has not defined BSD::Resource macro ...
340
341           The code tried to call getrlimit/setrlimit for a resource limit
342           that your operating system vendor/supplier does not support.
343           Portable code should use get_rlimits() to check which resource
344           limits are defined.
345

EXAMPLES

347               # the user and system times so far by the process itself
348
349               ($usertime, $systemtime) = getrusage();
350
351               # ditto in OO way
352
353               $ru = getrusage();
354
355               $usertime   = $ru->utime;
356               $systemtime = $ru->stime;
357
358               # get the current priority level of this process
359
360               $currprio = getpriority();
361

KNOWN ISSUES

363       In AIX (at least version 3, maybe later also releases) if the BSD
364       compatibility library is not installed or not found by the
365       BSD::Resource installation procedure and when using the getpriority()
366       or setpriority(), the "PRIO_MIN" is 0 (corresponding to -20) and
367       "PRIO_MAX" is 39 (corresponding to 19, the BSD priority 20 is
368       unreachable).
369
370       In HP-UX the getrusage() is not Officially Supported at all but for the
371       time being, it does seem to be.
372
373       In Mac OS X a normal user cannot raise the "RLIM_NPROC" over the
374       maxprocperuid limit (the default value is 266, try the command "sysctl
375       -a kern.maxprocperuid").
376
377       In NetBSD "RLIMIT_STACK" setrlimit() calls fail.
378
379       In Cygwin "RLIMIT_STACK" setrlimit calls fail.  Also, setrlimit()
380       "RLIMIT_NOFILE/RLIMIT_OFILE/RLIMIT_OFILE" calls return success, but
381       then the subsequent getrlimit calls show that the limits didn't really
382       change.
383
384       Because not all UNIX kernels are BSD and also because of the sloppy
385       support of getrusage() by many vendors many of the getrusage() values
386       may not be correctly updated.  For example Solaris 1 claims in
387       "<sys/rusage.h>" that the "ixrss" and the "isrss" fields are always
388       zero.  In SunOS 5.5 and 5.6 the getrusage() leaves most of the fields
389       zero and therefore getrusage() is not even used, instead of that the
390       /proc interface is used.  The mapping is not perfect: the "maxrss"
391       field is really the current resident size instead of the maximum, the
392       "idrss" is really the current heap size instead of the integral data,
393       and the "isrss" is really the current stack size instead of the
394       integral stack.  The ixrss has no sensible counterpart at all so it
395       stays zero.
396
398       Copyright 1995-2017 Jarkko Hietaniemi All Rights Reserved
399
400       This module free software; you can redistribute it and/or modify it
401       under the terms of the Artistic License 2.0 or GNU Lesser General
402       Public License 2.0.  For more details, see the full text of the
403       licenses at <http://www.perlfoundation.org/artistic_license_2_0>, and
404       <http://www.gnu.org/licenses/gpl-2.0.html>.
405

AUTHOR

407       Jarkko Hietaniemi, "jhi@iki.fi"
408
409
410
411perl v5.34.0                      2022-01-20                       Resource(3)
Impressum