NAME

getrusage − get information about resource utilization

SYNOPSIS

#include <sys/time.h>
#include <sys/rusage.h>

int 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 interpretation for some values reported, such as ru_idrss, are dependent on the clock tick interval.  This interval is an implementation dependent value; for example, on Sun-3 sytems the clock tick interval is 1/50 of a second, while on Sun-4 systems the clock tick interval is 1/100 of a second. 

The who parameter is one of RUSAGE_SELF or RUSAGE_CHILDREN.  The buffer to which rusage points will be filled with a structure with the following members:

struct timestruc ru_utime;/∗ user time used ∗/
struct timestruc ru_stime;/∗ system time used ∗/
intru_maxrss;/∗ maximum resident set size ∗/
intru_ixrss;/∗ currently 0 ∗/
intru_idrss;/∗ integral resident set size ∗/
intru_isrss;/∗ currently 0 ∗/
intru_minflt;/∗ page faults not requiring physical I/O ∗/
intru_majflt;/∗ page faults requiring physical I/O ∗/
intru_nswap;/∗ swaps ∗/
intru_inblock;/∗ block input operations ∗/
intru_oublock;/∗ block output operations ∗/
intru_msgsnd;/∗ messages sent ∗/
intru_msgrcv;/∗ messages received ∗/
intru_nsignals;/∗ signals received ∗/
intru_nvcsw;/∗ voluntary context switches ∗/
intru_nivcsw;/∗ involuntary context switches ∗/

The fields 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 sysconf(3C) function).  Also, see WARNINGS. 

ru_ixrss Currently 0. 

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 process 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 WARNINGS. 

ru_isrss Currently 0. 

ru_minflt The number of page faults serviced which did not require any physical I/O activity.  Also, see WARNINGS. 

ru_majflt The number of page faults serviced that required physical I/O activity.  This would include page ahead operations by the kernel.  Also, see WARNINGS. 

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 availability 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

getrusage() returns:

0 on success. 

−1 on failure and sets errno to indicate the error. 

ERRORS

EFAULT rusage points to an illegal address. 

EINVAL The who parameter is not a valid value. 

SEE ALSO

read(2), wait(2), write(2), gettimeofday(3C), sysconf(3C)

WARNINGS

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 that is not in memory.  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 housekeeping.  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.  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 that 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, anyone doing a read(2) or write(2) to something that is in the page cache will get a minor page fault(s) as well. 

BUGS

There is no way to obtain information about a child process that has not yet terminated. 

SunOS 5.1  —  Last change: 20 Oct 1992