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,
49 $maxrss, $ixrss, $idrss, $isrss, $minflt, $majflt, $nswap,
50 $inblock, $oublock, $msgsnd, $msgrcv,
51 $nsignals, $nvcsw, $nivcsw) = getrusage($ru_who);
52 $rusage = getrusage($ru_who);
54 # $ru_who argument is optional; it defaults to RUSAGE_SELF
56 $rusage = getrusage();
58 The $ru_who argument is either "RUSAGE_SELF" (the current process) or
60 "RUSAGE_CHILDREN" (all the child processes of the current process) or
61 it maybe left away in which case "RUSAGE_SELF" is used.
62 The "RUSAGE_CHILDREN" is the total sum of all the so far terminated
64 (either successfully or unsuccessfully) child processes: there is no
65 way to find out information about child processes still running.
66 On some systems (those supporting both getrusage() and the POSIX
68 threads) there is also "RUSAGE_THREAD". The BSD::Resource supports the
69 "RUSAGE_THREAD" if it is present but understands nothing more about the
70 POSIX threads themselves. Similarly for "RUSAGE_BOTH": some systems
71 support retrieving the sums of the self and child resource consumptions
72 simultaneously.
73 In list context getrusage() returns the current resource usages as a
75 list. On failure it returns an empty list.
76 The elements of the list are, in order: index name mean‐
78 ing usually (quite system dependent)
79 0 utime user time
81 1 stime system time
82 2 maxrss maximum shared memory or current resident set
83 3 ixrss integral shared memory
84 4 idrss integral or current unshared data
85 5 isrss integral or current unshared stack
86 6 minflt page reclaims
87 7 majflt page faults
88 8 nswap swaps
89 9 inblock block input operations
90 10 oublock block output operations
91 11 msgsnd messages sent
92 12 msgrcv messaged received
93 13 nsignals signals received
94 14 nvcsw voluntary context switches
95 15 nivcsw involuntary context switches
96 In scalar context getrusage() returns the current resource usages as a
98 an object. The object can be queried via methods named exactly like the
99 middle column, name, in the above table.
100 $ru = getrusage();
102 print $ru->stime, "\n";
103 $total_context_switches = $ru->nvcsw + $ru->nivcsw;
105 For a detailed description about the values returned by getrusage()
107 please consult your usual C programming documentation about getrusage()
108 and also the header file "<sys/resource.h>". (In Solaris, this might
109 be "<sys/rusage.h>").
110 See also "KNOWN ISSUES".
112 getrlimit
114 ($nowsoft, $nowhard) = getrlimit($resource);
116 $rlimit = getrlimit($resource);
118 The $resource argument can be one of
120 $resource usual meaning usual unit
122 RLIMIT_CPU CPU time seconds
124 RLIMIT_FSIZE file size bytes
126 RLIMIT_DATA data size bytes
128 RLIMIT_STACK stack size bytes
129 RLIMIT_CORE coredump size bytes
130 RLIMIT_RSS resident set size bytes
131 RLIMIT_MEMLOCK memory locked data size bytes
132 RLIMIT_NPROC number of processes 1
134 RLIMIT_NOFILE number of open files 1
136 RLIMIT_OFILE number of open files 1
137 RLIMIT_OPEN_MAX number of open files 1
138 RLIMIT_LOCKS number of file locks 1
140 RLIMIT_AS (virtual) address space bytes
142 RLIMIT_VMEM virtual memory (space) bytes
143 RLIMIT_TCACHE maximum number of 1
145 cached threads
146 RLIMIT_AIO_MEM maximum memory locked bytes
148 for POSIX AIO
149 RLIMIT_AIO_OPS maximum number 1
150 for POSIX AIO ops
151 What limits are available depends on the operating system. See below
153 for "get_rlimits()" on how to find out which limits are available, for
154 the exact documentation consult the documentation of your operatgiing
155 system. The two groups ("NOFILE", C"OFILE", <OPEN_MAX>) and ("AS",
156 "VMEM") are aliases within themselves.
157 Two meta-resource-symbols might exist
159 RLIM_NLIMITS
161 RLIM_INFINITY
162 "RLIM_NLIMITS" being the number of possible (but not necessarily fully
164 supported) resource limits, see also the get_rlimits() call below.
165 "RLIM_INFINITY" is useful in setrlimit(), the "RLIM_INFINITY" is repre‐
166 sented as -1.
167 In list context "getrlimit()" returns the current soft and hard
169 resource limits as a list. On failure it returns an empty list.
170 Processes have soft and hard resource limits. On crossing the soft
172 limit they receive a signal (for example the "SIGXCPU" or "SIGXFSZ",
173 corresponding to the "RLIMIT_CPU" and "RLIMIT_FSIZE", respectively).
174 The processes can trap and handle some of these signals, please see
175 "Signals" in perlipc. After the hard limit the processes will be ruth‐
176 lessly killed by the "KILL" signal which cannot be caught.
177 NOTE: the level of 'support' for a resource varies. Not all the systems
179 a) even recognise all those limits
181 b) really track the consumption of a resource
182 c) care (send those signals) if a resource limit is exceeded
183 Again, please consult your usual C programming documentation.
185 One notable exception for the better: officially HP-UX does not support
187 getrlimit() at all but for the time being, it does seem to.
188 In scalar context getrlimit() returns the current soft and hard
190 resource limits as an object. The object can be queried via methods
191 "cur" and "max", the current and maximum resource limits for the
192 $resource, respectively.
193 getpriority
195 $nowpriority = getpriority($pr_which, $pr_who);
197 # the default $pr_who is 0 (the current $pr_which)
199 $nowpriority = getpriority($pr_which);
201 # the default $pr_which is PRIO_PROCESS (the process priority)
203 $nowpriority = getpriority();
205 getpriority() returns the current priority. NOTE: getpriority() can
207 return zero or negative values completely legally. On failure getprior‐
208 ity() returns "undef" (and $! is set as usual).
209 The priorities returned by getpriority() are in the (inclusive) range
211 "PRIO_MIN"..."PRIO_MAX". The $pr_which argument can be any of
212 PRIO_PROCESS (a process) "PRIO_USER" (a user), or "PRIO_PGRP" (a
213 process group). The $pr_who argument tells which process/user/process
214 group, 0 signifying the current one.
215 Usual values for "PRIO_MIN", "PRIO_MAX", are -20, 20. A negative value
217 means better priority (more impolite process), a positive value means
218 worse priority (more polite process).
219 setrlimit
221 $success = setrlimit($resource, $newsoft, $newhard);
223 setrlimit() returns true on success and "undef" on failure.
225 NOTE: A normal user process can only lower its resource limits. Soft
227 or hard limit "RLIM_INFINITY" means as much as possible, the real hard
228 limits are normally buried inside the kernel and are very system-depen‐
229 dent.
230 setpriority
232 $success = setpriority($pr_which, $pr_who, $priority);
234 # NOTE! If there are two arguments the second one is
236 # the new $priority (not $pr_who) and the $pr_who is
237 # defaulted to 0 (the current $pr_which)
238 $success = setpriority($pr_which, $priority);
240 # The $pr_who defaults to 0 (the current $pr_which) and
242 # the $priority defaults to half of the PRIO_MAX, usually
243 # that amounts to 10 (being a nice $pr_which).
244 $success = setpriority($pr_which);
246 # The $pr_which defaults to PRIO_PROCESS,
248 $success = setpriority();
250 setpriority() is used to change the scheduling priority. A positive
252 priority means a more polite process/process group/user; a negative
253 priority means a more impoite process/process group/user. The priori‐
254 ties handled by setpriority() are ["PRIO_MIN","PRIO_MAX"]. A normal
255 user process can only lower its priority (make it more positive).
256 NOTE: A successful call returns 1, a failed one 0.
258 See also "KNOWN ISSUES".
260 times
262 use BSD::Resource qw(times);
264 ($user, $system, $child_user, $child_system) = times();
266 The BSD::Resource module offers a times() implementation that has usu‐
268 ally slightly better time granularity than the times() by Perl core.
269 The time granularity of the latter is usually 1/60 seconds while the
270 former may achieve submilliseconds.
271 NOTE: The current implementation uses two getrusage() system calls: one
273 with RUSAGE_SELF and one with RUSAGE_CHILDREN. Therefore the operation
274 is not `atomic': the times for the children are recorded a little bit
275 later.
276 NOTE: times() is not imported by default by BSD::Resource. You need to
278 tell that you want to use it.
279 NOTE: times() is not a "real BSD" function. It is older UNIX.
281 get_rlimits
283 $rlimits = get_rlimits();
285 NOTE: This is not a real BSD function. It is a convenience function.
287 get_rlimits() returns a reference to hash which has the names of the
289 available resource limits as keys and their indices (those which are
290 needed as the first argument to getrlimit() and setrlimit()) as values.
291 For example:
292 $r = get_rlimits();
294 print "ok.\n" if ($r->{'RLIM_STACK'} == RLIM_STACK);
295
297 ·
298 Your vendor has not defined BSD::Resource macro ...
299 The code tried to call getrlimit/setrlimit for a resource limit
301 that your operating system vendor/supplier does not support. Por‐
302 table code should use get_rlimits() to check which resource limits
303 are defined.
304 ·
306 use PRIO..., not "PRIO_..."
307 getpriority() and setpriority() use symbolic names, not strings,
309 for the constants.
310 ·
312 use RLIMIT..., not "RLIMIT_..."
313 getrlimit() and setrlimit() use symbolic names, not strings, for
315 the constants.
316
318 # the user and system times so far by the process itself
319 ($usertime, $systemtime) = getrusage();
321 # ditto in OO way
323 $ru = getrusage();
325 $usertime = $ru->utime;
327 $systemtime = $ru->stime;
328 # get the current priority level of this process
330 $currprio = getpriority();
332
334 In AIX if the BSD compatibility library is not installed or not found
335 by the BSD::Resource installation procedure and when using the getpri‐
336 ority() or setpriority(), the "PRIO_MIN" is 0 (corresponding to -20)
337 and "PRIO_MAX" is 39 (corresponding to 19, the BSD priority 20 is
338 unreachable).
339 In HP-UX the getrusage() is not Officially Supported at all but for the
341 time being, it does seem to be.
342 In Mac OS X releases from 10.3.2 (and probably earlier) to at least
344 10.4.6 the t/setrlimit.t subtest #9 will fail because of bug(s?) in the
345 setrlimit/getrlimit functionality, setting/getting resource limits on
346 the maximum number of processes (RLIM_NPROC) behaves nonsensically
347 (sometimes it works, sometimes it doesn't). The bug has been reported
348 to Apple.
349 Because not all UNIX kernels are BSD and also because of the sloppy
351 support of getrusage() by many vendors many of the getrusage() values
352 may not be correctly updated. For example Solaris 1 claims in
353 "<sys/rusage.h>" that the "ixrss" and the "isrss" fields are always
354 zero. In SunOS 5.5 and 5.6 the getrusage() leaves most of the fiels
355 zero and therefore getrusage() is not even used, instead of that the
356 /proc interface is used. The mapping is not perfect: the maxrss field
357 is really the current resident size instead of the maximum, the idrss
358 is really the current heap size instead of the integral data, and the
359 isrss is really the current stack size instead of the integral stack.
360 The ixrss has no sensible counterpart at all so it stays zero.
361
363 Copyright 1995-2004 Jarkko Hietaniemi All Rights Reserved
364 This library is free software; you may redistribute it and/or modify it
366 under the same terms as Perl itself.
367
369 Jarkko Hietaniemi, "jhi@iki.fi"
370perl v5.8.8 2006-05-26 Resource(3)