What is getrusage()?
As a process runs, the Linux kernel silently tracks how many CPU seconds it has consumed, how many times it page-faulted, how many times it was preempted, and so on. The getrusage() system call gives your program access to those accumulated statistics. You call it, pass a pointer to a struct rusage, and the kernel fills that structure with the current resource usage figures.
The function is defined in SUSv3, but only the two CPU time fields (ru_utime and ru_stime) are mandated by the standard. All other fields are implementation-defined, which is why many of them are zero on Linux while being meaningful on BSD systems.
Function Signature
#include <sys/resource.h>
int getrusage(int who, struct rusage *res_usage);
/*
* Returns: 0 on success
* -1 on error (errno is set)
*
* who -- specifies WHOSE usage to retrieve (see below)
* res_usage -- pointer to struct rusage filled by the kernel
*/The function takes exactly two arguments. The first selects whose statistics you want. The second is an output pointer — the kernel writes the numbers into it. On error, errno is set to EINVAL if who has an unrecognised value.
The “who” Argument — Three Values
The who argument tells the kernel which entity’s resource usage you want. There are three valid values:
This includes all threads in the process. It is the most commonly used flag. Use it when you want to profile how much CPU your program consumed, how many page faults it triggered, etc. Available since the original POSIX standard.
Important: this only accumulates statistics for children that have already terminated and for which the calling process has called wait() or waitpid(). Children still running are not included. Children that terminated but have not been waited for are also not included. See the dedicated file for the full accumulation rules.
Added in Linux kernel 2.6.26. Not portable — other UNIX systems do not support this flag. Use it in multi-threaded applications when you want per-thread statistics rather than the whole-process totals that RUSAGE_SELF gives you. Requires _GNU_SOURCE to be defined before including the header.
Relationship to times() and /proc
Similar CPU time information is also available from two other sources:
- The
times()system call (Section 10.7 of TLPI) returns CPU time in clock ticks rather than microseconds. - The Linux-specific
/proc/PID/statfile exposes CPU time and page fault counts for all processes on the system. It can be read by any process that has permission, making it useful for monitoring other processes, not just your own.
/* Read /proc/self/stat to see your own stats without getrusage() */
FILE *f = fopen("/proc/self/stat", "r");
/* Field 14 = utime (jiffies), 15 = stime, 10 = minflt, 12 = majflt */
/* See man 5 proc for complete field layout */Code Example — Using getrusage(RUSAGE_SELF)
#include <stdio.h>
#include <stdlib.h>
#include <sys/resource.h>
int main(void)
{
struct rusage ru;
long i;
/* Burn some user-mode CPU time */
for (i = 0; i < 200000000L; i++)
;
/* Retrieve this process's own resource usage */
if (getrusage(RUSAGE_SELF, &ru) == -1) {
perror("getrusage");
exit(EXIT_FAILURE);
}
/* Print results.
ru_utime and ru_stime are struct timeval:
tv_sec = whole seconds
tv_usec = microseconds part (0 to 999999) */
printf("User CPU time : %ld sec %ld usec\n",
(long)ru.ru_utime.tv_sec,
(long)ru.ru_utime.tv_usec);
printf("System CPU time: %ld sec %ld usec\n",
(long)ru.ru_stime.tv_sec,
(long)ru.ru_stime.tv_usec);
printf("Peak RSS : %ld KB\n", ru.ru_maxrss);
printf("Minor faults : %ld\n", ru.ru_minflt);
printf("Major faults : %ld\n", ru.ru_majflt);
printf("Vol ctx sw : %ld\n", ru.ru_nvcsw);
printf("Invol ctx sw : %ld\n", ru.ru_nivcsw);
return 0;
}
/*
* Compile: gcc -o getrusage_demo getrusage_demo.c
* Run: ./getrusage_demo
*
* Expected output (approximate):
* User CPU time : 0 sec 450000 usec
* System CPU time: 0 sec 2000 usec
* Peak RSS : 1364 KB
* Minor faults : 72
* Major faults : 0
* Vol ctx sw : 0
* Invol ctx sw : 2
*/Interview Questions
Requires #include <sys/resource.h>. Returns 0 on success and -1 on error with errno set. On error, errno is typically EINVAL (invalid who argument) or EFAULT (bad pointer).
RUSAGE_SELF — the calling process (all threads). RUSAGE_CHILDREN — all terminated and waited-for children. RUSAGE_THREAD — the calling thread only (Linux 2.6.26+, not portable).
Only partially. SUSv3 specifies getrusage() but mandates only the two CPU time fields: ru_utime and ru_stime. All other fields are implementation-defined. Many fields that are zero on Linux carry useful data on BSD-family systems. Code that relies on fields beyond the two CPU time fields is not portable.
/proc/PID/stat — this file exposes CPU time (in jiffies) and page fault counts for any process on the system, not just your own. It is readable by any process with appropriate permissions. The proc(5) man page documents the field layout.
You need to define _GNU_SOURCE before including headers, either with #define _GNU_SOURCE in your source file or with -D_GNU_SOURCE on the compiler command line. RUSAGE_THREAD is Linux-specific and is hidden behind the GNU extension feature test macro.