getrusage(2) getrusage(2)
NAME
getrusage - get information about resource utilization
SYNOPSIS
#include <sys/time.h>
#include <sys/resource.h>
getrusage(int who, struct rusage *rusage);
DESCRIPTION
getrusage returns information about the resources utilized by the
current process, or all its terminated child processes. The interpre-
tation for some values reported, such as ruidrss, are dependent on
the clock tick interval. This interval is an implementation dependent
value.
The who parameter is one of RUSAGESELF or RUSAGECHILDREN. The buffer
to which rusage points will be filled in with the following structure:
struct rusage {
struct timeval ruutime; /* user time used */
struct timeval rustime; /* system time used */
int rumaxrss; /* maximum resident set size */
int ruixrss; /* currently 0 */
int ruidrss; /* integral resident set size */
int ruisrss; /* currently 0 */
int ruminflt; /* page faults not requiring physical I/O */
int rumajflt; /* page faults requiring physical I/O */
int runswap; /* swaps */
int ruinblock; /* block input operations */
int ruoublock; /* block output operations */
int rumsgsnd; /* messages sent */
int rumsgrcv; /* messages received */
int runsignals; /* signals received */
int runvcsw; /* voluntary context switches */
int runivcsw; /* involuntary context switches */
};
The fields are interpreted as follows:
ruutime The total amount of time spent executing in user mode.
Time is given in seconds and microseconds.
rustime The total amount of time spent executing in system
mode. Time is given in seconds and microseconds.
rumaxrss The maximum resident set size. Size is given in pages
(the size of a page, in bytes, is given by the
getpagesize(3) system call). Also, see NOTES.
ruixrss Currently returns 0.
Page 1 Reliant UNIX 5.44 Printed 11/98
getrusage(2) getrusage(2)
ruidrss An "integral" value indicating the amount of memory in
use by a process while the process is running. This
value is the sum of the resident set sizes of the pro-
cess running when a clock tick occurs. The value is
given in pages times clock ticks. Note: it does not
take sharing into account. Also, see NOTES.
ruisrss Currently returns 0.
ruminflt The number of page faults serviced which did not
require any physical I/O activity. Also, see NOTES.
rumajflt The number of page faults serviced which required phy-
sical I/O activity. This could include page ahead
operations by the kernel. Also, see NOTES.
runswap The number of times a process was swapped out of main
memory.
ruinblock The number of times the file system had to perform
input in servicing a read(2) request.
ruoublock The number of times the file system had to perform out-
put in servicing a write(2) request.
rumsgsnd The number of messages sent over sockets.
rumsgrcv The number of messages received from sockets.
runsignals The number of signals delivered.
runvcsw The number of times a context switch resulted due to a
process voluntarily giving up the processor before its
time slice was completed (usually to await availability
of a resource).
runivcsw The number of times a context switch resulted due to a
higher priority process becoming runnable or because
the current process exceeded its time slice.
RETURN VALUE
If successful, the value of the appropriate structure is filled in,
and 0 is returned. If the call fails, a -1 is returned.
Page 2 Reliant UNIX 5.44 Printed 11/98
getrusage(2) getrusage(2)
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
getrusage will fail if:
EINVAL The who parameter is not a valid value.
EFAULT The address specified by the rusage argument is not in a
valid portion of the process' address space.
NOTES
The numbers ruinblock and ruoublock account only for real I/O, and
are approximate measures at best. Data supplied by the caching mechan-
ism is charged only to the first process to read and the last process
to write the data.
The way resident set size is calculated is an approximation, and could
misrepresent the true resident set size.
Page faults can be generated from a variety of sources and for a
variety of reasons. The customary cause for a page fault is a direct
reference by the program to a page which is not in memory. Now, how-
ever, the kernel can generate page faults on behalf of the user, for
example, servicing read(2) and write(2) system calls. Also, a page
fault can be caused by an absent hardware translation to a page, even
though the page is in physical memory.
In addition to hardware detected page faults, the kernel may cause
pseudo page faults in order to perform some housekeeping. For example,
the kernel may generate page faults, even if the pages exist in physi-
cal memory, in order to lock down pages involved in a raw I/O request.
By definition, major page faults require physical I/O, while minor
page faults do not require physical I/O. For example, reclaiming the
page from the free list would avoid I/O and generate a minor page
fault. More commonly, minor page faults occur during process startup
as references to pages which are already in memory. For example, if an
address space faults on some "hot" executable or shared library, this
results in a minor page fault for the address space. Also, any one
doing a read(2) or write(2) to something that is in the page cache
will get a minor page fault(s) as well.
There is no way to obtain information about a child process which has
not yet terminated.
SEE ALSO
sar(1M), read(2), times(2), wait(2), write(2), getpagesize(3),
gettimeofday(3C), resource(5), systime(5).
Page 3 Reliant UNIX 5.44 Printed 11/98