getrusage(3C)
NAME
getrusage - get information about resource utilization
SYNOPSIS
#include <sys/resource.h>
int getrusage(int who, struct rusage *r_usage);
DESCRIPTION
The getrusage() function provides measures of the resources
used by the current process or its terminated and waited-for
child processes. If the value of the who argument is
RUSAGE_SELF, information is returned about resources used by
the current process. If the value of the who argument is
RUSAGE_CHILDREN, information is returned about resources
used by the terminated and waited-for children of the
current process. If the child is never waited for (for
instance, if the parent has SA_NOCLDWAIT set or sets SIGCHLD
to SIG_IGN), the resource information for the child process
is discarded and not included in the resource information
provided by getrusage().
The r_usage argument is a pointer to an object of type
struct rusage in which the returned information is stored.
The members of rusage are as follows:
struct timeval ru_utime; /* user time used */
struct timeval ru_stime; /* system time used */
long ru_maxrss; /* maximum resident set size */
long ru_idrss; /* integral resident set size */
long ru_minflt; /* page faults not requiring physical I/O */
long ru_majflt; /* page faults requiring physical I/O */
long ru_nswap; /* swaps */
long ru_inblock; /* block input operations */
long ru_oublock; /* block output operations */
long ru_msgsnd; /* messages sent */
long ru_msgrcv; /* messages received */
long ru_nsignals; /* signals received */
long ru_nvcsw; /* voluntary context switches */
long ru_nivcsw; /* involuntary context switches */
The structure members are interpreted as follows:
ru_utime
The total amount of time spent executing in user mode.
Time is given in seconds and microseconds.
ru_stime
The total amount of time spent executing in system
mode. Time is given in seconds and microseconds.
ru_maxrss
The maximum resident set size. Size is given in pages
(the size of a page, in bytes, is given by the
getpagesize(3C) function). See the NOTES section of
this page.
ru_idrss
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. It does not take
sharing into account. See the NOTES section of this
page.
ru_minflt
The number of page faults serviced which did not
require any physical I/O activity. See the NOTES sec-
tion of this page.
ru_majflt
The number of page faults serviced which required phy-
sical I/O activity. This could include page ahead
operations by the kernel. See the NOTES section of
this page.
ru_nswap
The number of times a process was swapped out of main
memory.
ru_inblock
The number of times the file system had to perform
input in servicing a read(2) request.
ru_oublock
The number of times the file system had to perform
output in servicing a write(2) request.
ru_msgsnd
The number of messages sent over sockets.
ru_msgrcv
The number of messages received from sockets.
ru_nsignals
The number of signals delivered.
ru_nvcsw
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 availabil-
ity of a resource).
ru_nivcsw
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 VALUES
Upon successful completion, getrusage() returns 0. Other-
wise, -1 is returned and errno is set to indicate the error.
ERRORS
The getrusage() function will fail if:
EFAULT
The address specified by the r_usage argument is not
in a valid portion of the process' address space.
EINVAL
The who parameter is not a valid value.
SEE ALSO
sar(1M), read(2), times(2), wait(2), write(2),
getpagesize(3C), gettimeofday(3C)
NOTES
Only the timeval member of struct rusage are supported in
this implementation.
The numbers ru_inblock and ru_oublock account only for real
I/O, and are approximate measures at best. Data supplied by
the cache mechanism 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, however, the kernel can generate
page faults on behalf of the user, for example, servicing
read(2) and write(2) functions. 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 housekeep-
ing. For example, the kernel may generate page faults, even
if the pages exist in physical 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.
Man(1) output converted with
man2html