getrusage(S)

getrusage -- get information about resource utilization

Synopsis

   cc. . . -lc
   
   #include <sys/time.h>
   #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.

   struct  rusage {
           struct timeval ru_utime;        /* user time used */
           struct timeval ru_stime;        /* system time used */
           long    ru_maxrss;
   #define ru_first        ru_ixrss
           long    ru_ixrss;               /* XXX: 0 */
           long    ru_idrss;               /* XXX: sum of rm_asrss */
           long    ru_isrss;               /* XXX: 0 */
           long    ru_minflt;              /* any page faults not requiring I/O */
           long    ru_majflt;              /* any page faults requiring 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 */
   #define ru_last         ru_nivcsw
   };

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 getpagesize(S) system call).
ru_ixrss: Currently returns 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.
ru_isrss: Currently returns 0.
ru_minflt: The number of page faults serviced which did not require any physical I/O activity.
ru_majflt: The number of page faults serviced which required physical I/O activity. This could include page ahead operations by the kernel.
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(S) request.
ru_oublock: The number of times the file system had to perform output in servicing a write(S) 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

If successful, the r_usage structure is filled in and 0 is returned. If the call fails, a -1 is returned and errno is set to indicate the error.

Errors

getrusage will fail if:

EINVAL: The who argument is not a valid value.
EFAULT: The address specified by the rusage argument is not in a valid portion of the process's address space.

An invalid address for the r_usage argument may result in a core dump as opposed to returning EFAULT.

Notices

Only the timeval fields of struct rusage are supported in this implementation.

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

Standards conformance

This routine conforms to X/Open System Interfaces and Headers, Issue 4, Version 2.