Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

getrusage()

Get information about resource utilization

Synopsis:

#include <sys/resource.h>

int getrusage( int who,
               struct rusage * r_usage );

Arguments:

who
Which process to get the usage for:
r_usage
A pointer to an object of type struct rusage in which the function can store the resource information; see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The getrusage() function provides measures of the resources used by the current process or its terminated and waited-for child processes, depending on the value of the who argument.

The rusage structure is defined as:

struct timeval  ru_utime;    /* user time used */
struct timeval  ru_stime;    /* system time used */
long            ru_maxrss;   /* max resident set size */
long            ru_ixrss;    /* integral shared memory size */
long            ru_idrss;    /* integral unshared data " */
long            ru_isrss;    /* integral unshared stack " */
long            ru_minflt;   /* page reclaims */
long            ru_majflt;   /* page faults */
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 " */

The members include:

ru_utime
The total amount of time, in seconds and microseconds, spent executing in user mode.
ru_stime
The total amount of time, in seconds and microseconds, spent executing in system mode.
ru_maxrss
The maximum resident set size, given in pages. See the Caveats section, below.
ru_ixrss
Not currently supported.
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. It doesn't take sharing into account. See the Caveats section, below.
ru_isrss
Not currently supported.
ru_minflt
The number of page faults serviced that didn't require any physical I/O activity. See the Caveats section, below.
ru_majflt
The number of page faults serviced that required physical I/O activity. This could include page ahead operations by the kernel. See the Caveats section, below
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() request.
ru_oublock
The number of times the filesystem had to perform output in servicing a write() 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's voluntarily giving up the processor before its timeslice 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's becoming runnable or because the current process exceeded its time slice.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EFAULT
The address specified by the r_usage argument isn't in a valid portion of the process's address space.
EINVAL
Invalid who parameter.

Classification:

POSIX 1003.1 XSI

Safety:
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:

Only the timeval fields of struct rusage are supported.

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 isn't in memory. Now, however, the kernel can generate page faults on behalf of the user, for example, servicing read() and write() 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 don't. 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, a minor page fault results for the address space. Also, anyone doing a read() or write() to something that's in the page cache gets a minor page fault(s) as well.

There's no way to obtain information about a child process that hasn't yet terminated.

See also:

gettimeofday(), read(), times(), wait(), write()