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_TCACHE maximum number of 1
143 cached threads
144 RLIMIT_AIO_MEM maximum memory locked bytes
146 for POSIX AIO
147 RLIMIT_AIO_OPS maximum number 1
148 for POSIX AIO ops
149 What limits are available depends on the operating system. See below
151 for "get_rlimits()" on how to find out which limits are available, for
152 the exact documentation consult the documentation of your operatgiing
153 system. The two groups ("NOFILE", C"OFILE", <OPEN_MAX>) and ("AS",
154 "VMEM") are aliases within themselves.
155 Two meta-resource-symbols might exist
157 RLIM_NLIMITS
159 RLIM_INFINITY
160 "RLIM_NLIMITS" being the number of possible (but not necessarily fully
162 supported) resource limits, see also the get_rlimits() call below.
163 "RLIM_INFINITY" is useful in setrlimit(), the "RLIM_INFINITY" is often
164 represented as minus one (-1).
165 In list context "getrlimit()" returns the current soft and hard
167 resource limits as a list. On failure it returns an empty list.
168 Processes have soft and hard resource limits. On crossing the soft
170 limit they receive a signal (for example the "SIGXCPU" or "SIGXFSZ",
171 corresponding to the "RLIMIT_CPU" and "RLIMIT_FSIZE", respectively).
172 The processes can trap and handle some of these signals, please see
173 "Signals" in perlipc. After the hard limit the processes will be
174 ruthlessly killed by the "KILL" signal which cannot be caught.
175 NOTE: the level of 'support' for a resource varies. Not all the systems
177 a) even recognise all those limits
179 b) really track the consumption of a resource
180 c) care (send those signals) if a resource limit is exceeded
181 Again, please consult your usual C programming documentation.
183 One notable exception for the better: officially HP-UX does not support
185 getrlimit() at all but for the time being, it does seem to.
186 In scalar context "getrlimit()" returns the current soft limit. On
188 failure it returns "undef".
189 getpriority
191 $nowpriority = getpriority($pr_which, $pr_who);
192 # the default $pr_who is 0 (the current $pr_which)
194 $nowpriority = getpriority($pr_which);
196 # the default $pr_which is PRIO_PROCESS (the process priority)
198 $nowpriority = getpriority();
200 getpriority() returns the current priority. NOTE: getpriority() can
202 return zero or negative values completely legally. On failure
203 getpriority() returns "undef" (and $! is set as usual).
204 The priorities returned by getpriority() are in the (inclusive) range
206 "PRIO_MIN"..."PRIO_MAX". The $pr_which argument can be any of
207 PRIO_PROCESS (a process) "PRIO_USER" (a user), or "PRIO_PGRP" (a
208 process group). The $pr_who argument tells which process/user/process
209 group, 0 signifying the current one.
210 Usual values for "PRIO_MIN", "PRIO_MAX", are -20, 20. A negative value
212 means better priority (more impolite process), a positive value means
213 worse priority (more polite process).
214 setrlimit
216 $success = setrlimit($resource, $newsoft, $newhard);
217 setrlimit() returns true on success and "undef" on failure.
219 NOTE: A normal user process can only lower its resource limits. Soft
221 or hard limit "RLIM_INFINITY" means as much as possible, the real hard
222 limits are normally buried inside the kernel and are very system-
223 dependent.
224 NOTE: Even the soft limit that is actually set might be lower than what
226 requested for various reasons. One possibility is that the actual
227 limit on a resource might be controlled by some system variable (e.g.
228 in BSD systems the RLIMIT_NPROC can be capped by the system variable
229 "maxprocperuid", try "sysctl -a kern.maxprocperuid"), or in many
230 environments core dumping has been disabled from normal user processes.
231 Another possibility is that a limit is rounded down to some alignment
232 or granularity, for example the memory limits might be rounded down to
233 the closest 4 kilobyte boundary. In other words, do not expect to be
234 able to setrlimit() a limit to a value and then be able to read back
235 the same value with getrlimit().
236 setpriority
238 $success = setpriority($pr_which, $pr_who, $priority);
239 # NOTE! If there are two arguments the second one is
241 # the new $priority (not $pr_who) and the $pr_who is
242 # defaulted to 0 (the current $pr_which)
243 $success = setpriority($pr_which, $priority);
245 # The $pr_who defaults to 0 (the current $pr_which) and
247 # the $priority defaults to half of the PRIO_MAX, usually
248 # that amounts to 10 (being a nice $pr_which).
249 $success = setpriority($pr_which);
251 # The $pr_which defaults to PRIO_PROCESS.
253 $success = setpriority();
255 setpriority() is used to change the scheduling priority. A positive
257 priority means a more polite process/process group/user; a negative
258 priority means a more impoite process/process group/user. The
259 priorities handled by setpriority() are ["PRIO_MIN","PRIO_MAX"]. A
260 normal user process can only lower its priority (make it more
261 positive).
262 NOTE: A successful call returns 1, a failed one 0.
264 See also "KNOWN ISSUES".
266 times
268 use BSD::Resource qw(times);
269 ($user, $system, $child_user, $child_system) = times();
271 The BSD::Resource module offers a times() implementation that has
273 usually slightly better time granularity than the times() by Perl core.
274 The time granularity of the latter is usually 1/60 seconds while the
275 former may achieve submilliseconds.
276 NOTE: The current implementation uses two getrusage() system calls: one
278 with RUSAGE_SELF and one with RUSAGE_CHILDREN. Therefore the operation
279 is not `atomic': the times for the children are recorded a little bit
280 later.
281 NOTE: times() is not imported by default by BSD::Resource. You need to
283 tell that you want to use it.
284 NOTE: times() is not a "real BSD" function. It is older UNIX.
286 get_rlimits
288 use BSD::Resource qw{get_rlimits};
289 my $limits = get_rlimits();
290 NOTE: This is not a real BSD function. It is a convenience function
292 introduced by BSD::Resource.
293 get_rlimits() returns a reference to hash which has the names of the
295 available resource limits as keys and their indices (those which are
296 needed as the first argument to getrlimit() and setrlimit()) as values.
297 For example:
298 use BSD::Resource qw{get_rlimits};
300 my $limits = get_rlimits();
301 for my $name (keys %$limits) {
302 my ($soft, $hard) = BSD::Resource::getrlimit($limits->{$name});
303 print "$name soft $soft hard $hard\n";
304 }
305 Note that a limit of -1 means unlimited.
307
309 ยท
310 Your vendor has not defined BSD::Resource macro ...
313 The code tried to call getrlimit/setrlimit for a resource limit
315 that your operating system vendor/supplier does not support.
316 Portable code should use get_rlimits() to check which resource
317 limits are defined.
318
320 # the user and system times so far by the process itself
321 ($usertime, $systemtime) = getrusage();
323 # ditto in OO way
325 $ru = getrusage();
327 $usertime = $ru->utime;
329 $systemtime = $ru->stime;
330 # get the current priority level of this process
332 $currprio = getpriority();
334
336 In AIX (at least version 3, maybe later also releases) if the BSD
337 compatibility library is not installed or not found by the
338 BSD::Resource installation procedure and when using the getpriority()
339 or setpriority(), the "PRIO_MIN" is 0 (corresponding to -20) and
340 "PRIO_MAX" is 39 (corresponding to 19, the BSD priority 20 is
341 unreachable).
342 In HP-UX the getrusage() is not Officially Supported at all but for the
344 time being, it does seem to be.
345 In Mac OS X a normal user cannot raise the RLIM_NPROC over the
347 maxprocperuid limit (the default value is 266, try the command "sysctl
348 -a kern.maxprocperuid").
349 In NetBSD RLIMIT_STACK calls fail.
351 Because not all UNIX kernels are BSD and also because of the sloppy
353 support of getrusage() by many vendors many of the getrusage() values
354 may not be correctly updated. For example Solaris 1 claims in
355 "<sys/rusage.h>" that the "ixrss" and the "isrss" fields are always
356 zero. In SunOS 5.5 and 5.6 the getrusage() leaves most of the fiels
357 zero and therefore getrusage() is not even used, instead of that the
358 /proc interface is used. The mapping is not perfect: the "maxrss"
359 field is really the current resident size instead of the maximum, the
360 "idrss" is really the current heap size instead of the integral data,
361 and the "isrss" is really the current stack size instead of the
362 integral stack. The ixrss has no sensible counterpart at all so it
363 stays zero.
364
366 Copyright 1995-2010 Jarkko Hietaniemi All Rights Reserved
367 This library is free software; you may redistribute it and/or modify it
369 under the same terms as Perl itself.
370
372 Jarkko Hietaniemi, "jhi@iki.fi"
373perl v5.12.0 2010-03-15 Resource(3)