1Resource(3) User Contributed Perl Documentation Resource(3)
2
6 BSD::Resource - BSD process resource limit and priority functions
7
9 use BSD::Resource;
10 #
12 # the process resource consumption so far
13 #
14 ($usertime, $systemtime,
16 $maxrss, $ixrss, $idrss, $isrss, $minflt, $majflt, $nswap,
17 $inblock, $oublock, $msgsnd, $msgrcv,
18 $nsignals, $nvcsw, $nivcsw) = getrusage($ru_who);
19 $rusage = getrusage($ru_who);
21 #
23 # the process resource limits
24 #
25 ($nowsoft, $nowhard) = getrlimit($resource);
27 $rlimit = getrlimit($resource);
29 $success = setrlimit($resource, $newsoft, $newhard);
31 #
33 # the process scheduling priority
34 #
35 $nowpriority = getpriority($pr_which, $pr_who);
37 $success = setpriority($pr_which, $pr_who, $priority);
39 # The following is not a BSD function.
41 # It is a Perlish utility for the users of BSD::Resource.
42 $rlimits = get_rlimits();
44
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 $rusage = getrusage($ru_who);
53 # $ru_who argument is optional; it defaults to RUSAGE_SELF
55 $rusage = getrusage();
57 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 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 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 In list context getrusage() returns the current resource usages as a
74 list. On failure it returns an empty list.
75 The elements of the list are, in order:
77 index name meaning usually (quite system dependent)
78 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 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 $ru = getrusage();
101 print $ru->stime, "\n";
102 $total_context_switches = $ru->nvcsw + $ru->nivcsw;
104 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 See also "KNOWN ISSUES".
111 getrlimit
113 ($nowsoft, $nowhard) = getrlimit($resource);
114 $rlimit = getrlimit($resource);
116 The $resource argument can be one of
118 $resource usual meaning usual unit
120 RLIMIT_CPU CPU time seconds
122 RLIMIT_FSIZE file size bytes
124 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 RLIMIT_NPROC number of processes 1
132 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 RLIMIT_LOCKS number of file locks 1
138 RLIMIT_AS (virtual) address space bytes
140 RLIMIT_VMEM virtual memory (space) bytes
141 RLIMIT_PTHREAD number of pthreads 1
143 RLIMIT_TCACHE maximum number of 1
144 cached threads
145 RLIMIT_AIO_MEM maximum memory locked bytes
147 for POSIX AIO
148 RLIMIT_AIO_OPS maximum number 1
149 for POSIX AIO ops
150 RLIMIT_FREEMEM portion of the total memory
152 RLIMIT_NTHR maximum number of 1
154 threads
155 RLIMIT_NPTS maximum number of 1
157 pseudo-terminals
158 RLIMIT_RSESTACK RSE stack size bytes
160 RLIMIT_SBSIZE socket buffer size bytes
162 RLIMIT_SWAP maximum swap size bytes
164 RLIMIT_MSGQUEUE POSIX mq size bytes
166 RLIMIT_RTPRIO maximum RT priority 1
168 RLIMIT_RTTIME maximum RT time microseconds
169 RLIMIT_SIGPENDING pending signals 1
170 What limits are available depends on the operating system.
172 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 The two groups ("NOFILE", "OFILE", "OPEN_MAX") and ("AS", "VMEM") are
178 aliases within themselves.
179 Two meta-resource-symbols might exist
181 RLIM_NLIMITS
183 RLIM_INFINITY
184 "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 In list context getrlimit() returns the current soft and hard resource
191 limits as a list. On failure it returns an empty list.
192 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 NOTE: the level of 'support' for a resource varies. Not all the systems
201 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 Again, please consult your usual C programming documentation.
207 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 In scalar context getrlimit() returns the current soft limit. On
212 failure it returns "undef".
213 getpriority
215 # $pr_which can be PRIO_USER, PRIO_PROCESS, or PRIO_PGRP,
216 # and in some systems PRIO_THREAD
217 $nowpriority = getpriority($pr_which, $pr_who);
219 # the default $pr_who is 0 (the current $pr_which)
221 $nowpriority = getpriority($pr_which);
223 # the default $pr_which is PRIO_PROCESS (the process priority)
225 $nowpriority = getpriority();
227 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 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 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 setrlimit
243 $success = setrlimit($resource, $newsoft, $newhard);
244 setrlimit() returns true on success and "undef" on failure.
246 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 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 setpriority
265 $success = setpriority($pr_which, $pr_who, $priority);
266 # 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 $success = setpriority($pr_which, $priority);
272 # 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 $success = setpriority($pr_which);
278 # The $pr_which defaults to PRIO_PROCESS.
280 $success = setpriority();
282 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 NOTE: A successful call returns 1, a failed one 0.
291 See also "KNOWN ISSUES".
293 times
295 use BSD::Resource qw(times);
296 ($user, $system, $child_user, $child_system) = times();
298 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 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 NOTE: times() is not imported by default by BSD::Resource. You need to
310 tell that you want to use it.
311 NOTE: times() is not a "real BSD" function. It is older UNIX.
313 get_rlimits
315 use BSD::Resource qw{get_rlimits};
316 my $limits = get_rlimits();
317 NOTE: This is not a real BSD function. It is a convenience function
319 introduced by BSD::Resource.
320 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 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 Note that a limit of -1 means unlimited.
334
336 •
337 Your vendor has not defined BSD::Resource macro ...
340 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
347 # the user and system times so far by the process itself
348 ($usertime, $systemtime) = getrusage();
350 # ditto in OO way
352 $ru = getrusage();
354 $usertime = $ru->utime;
356 $systemtime = $ru->stime;
357 # get the current priority level of this process
359 $currprio = getpriority();
361
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 In HP-UX the getrusage() is not Officially Supported at all but for the
371 time being, it does seem to be.
372 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 In NetBSD "RLIMIT_STACK" setrlimit() calls fail.
378 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 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 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
407 Jarkko Hietaniemi, "jhi@iki.fi"
408perl v5.38.0 2023-07-20 Resource(3)