1GETRUSAGE(2)               Linux Programmer's Manual              GETRUSAGE(2)
2
3
4

NAME

6       getrusage - get resource usage
7

SYNOPSIS

9       #include <sys/time.h>
10       #include <sys/resource.h>
11
12       int getrusage(int who, struct rusage *usage);
13

DESCRIPTION

15       getrusage()  returns  resource usage measures for who, which can be one
16       of the following:
17
18       RUSAGE_SELF
19              Return resource usage statistics for the calling process,  which
20              is the sum of resources used by all threads in the process.
21
22       RUSAGE_CHILDREN
23              Return resource usage statistics for all children of the calling
24              process that have terminated and been waited for.  These statis‐
25              tics  will include the resources used by grandchildren, and fur‐
26              ther removed descendants, if all of the intervening  descendants
27              waited on their terminated children.
28
29       RUSAGE_THREAD (since Linux 2.6.26)
30              Return  resource  usage  statistics for the calling thread.  The
31              _GNU_SOURCE feature test macro must be defined (before including
32              any  header file) in order to obtain the definition of this con‐
33              stant from <sys/resource.h>.
34
35       The resource usages are returned in the structure pointed to by  usage,
36       which has the following form:
37
38           struct rusage {
39               struct timeval ru_utime; /* user CPU time used */
40               struct timeval ru_stime; /* system CPU time used */
41               long   ru_maxrss;        /* maximum resident set size */
42               long   ru_ixrss;         /* integral shared memory size */
43               long   ru_idrss;         /* integral unshared data size */
44               long   ru_isrss;         /* integral unshared stack size */
45               long   ru_minflt;        /* page reclaims (soft page faults) */
46               long   ru_majflt;        /* page faults (hard page faults) */
47               long   ru_nswap;         /* swaps */
48               long   ru_inblock;       /* block input operations */
49               long   ru_oublock;       /* block output operations */
50               long   ru_msgsnd;        /* IPC messages sent */
51               long   ru_msgrcv;        /* IPC messages received */
52               long   ru_nsignals;      /* signals received */
53               long   ru_nvcsw;         /* voluntary context switches */
54               long   ru_nivcsw;        /* involuntary context switches */
55           };
56
57       Not  all  fields  are completed; unmaintained fields are set to zero by
58       the kernel.  (The unmaintained fields are  provided  for  compatibility
59       with  other  systems,  and  because  they  may  one day be supported on
60       Linux.)  The fields are interpreted as follows:
61
62       ru_utime
63              This is the total amount of time spent executing in  user  mode,
64              expressed in a timeval structure (seconds plus microseconds).
65
66       ru_stime
67              This is the total amount of time spent executing in kernel mode,
68              expressed in a timeval structure (seconds plus microseconds).
69
70       ru_maxrss (since Linux 2.6.32)
71              This is the maximum resident set size used (in kilobytes).   For
72              RUSAGE_CHILDREN,  this  is  the resident set size of the largest
73              child, not the maximum resident set size of the process tree.
74
75       ru_ixrss (unmaintained)
76              This field is currently unused on Linux.
77
78       ru_idrss (unmaintained)
79              This field is currently unused on Linux.
80
81       ru_isrss (unmaintained)
82              This field is currently unused on Linux.
83
84       ru_minflt
85              The number of page faults serviced  without  any  I/O  activity;
86              here  I/O  activity is avoided by “reclaiming” a page frame from
87              the list of pages awaiting reallocation.
88
89       ru_majflt
90              The number of page faults serviced that required I/O activity.
91
92       ru_nswap (unmaintained)
93              This field is currently unused on Linux.
94
95       ru_inblock (since Linux 2.6.22)
96              The number of times the filesystem had to perform input.
97
98       ru_oublock (since Linux 2.6.22)
99              The number of times the filesystem had to perform output.
100
101       ru_msgsnd (unmaintained)
102              This field is currently unused on Linux.
103
104       ru_msgrcv (unmaintained)
105              This field is currently unused on Linux.
106
107       ru_nsignals (unmaintained)
108              This field is currently unused on Linux.
109
110       ru_nvcsw (since Linux 2.6)
111              The number of times a context switch resulted due to  a  process
112              voluntarily  giving  up  the processor before its time slice was
113              completed (usually to await availability of a resource).
114
115       ru_nivcsw (since Linux 2.6)
116              The number of times a context switch resulted due  to  a  higher
117              priority  process  becoming  runnable  or  because  the  current
118              process exceeded its time slice.
119

RETURN VALUE

121       On success, zero is returned.  On error, -1 is returned, and  errno  is
122       set appropriately.
123

ERRORS

125       EFAULT usage points outside the accessible address space.
126
127       EINVAL who is invalid.
128

ATTRIBUTES

130       For   an   explanation   of   the  terms  used  in  this  section,  see
131       attributes(7).
132
133       ┌────────────┬───────────────┬─────────┐
134Interface   Attribute     Value   
135       ├────────────┼───────────────┼─────────┤
136getrusage() │ Thread safety │ MT-Safe │
137       └────────────┴───────────────┴─────────┘
138

CONFORMING TO

140       POSIX.1-2001,   POSIX.1-2008,   SVr4,   4.3BSD.    POSIX.1    specifies
141       getrusage(), but specifies only the fields ru_utime and ru_stime.
142
143       RUSAGE_THREAD is Linux-specific.
144

NOTES

146       Resource usage metrics are preserved across an execve(2).
147
148       Including <sys/time.h> is not required these days, but increases porta‐
149       bility.  (Indeed, struct timeval is defined in <sys/time.h>.)
150
151       In Linux kernel versions before 2.6.9, if the disposition of SIGCHLD is
152       set to SIG_IGN then the resource usages of child processes are automat‐
153       ically included in the  value  returned  by  RUSAGE_CHILDREN,  although
154       POSIX.1-2001  explicitly prohibits this.  This nonconformance is recti‐
155       fied in Linux 2.6.9 and later.
156
157       The structure definition shown at the start of this page was taken from
158       4.3BSD Reno.
159
160       Ancient  systems provided a vtimes() function with a similar purpose to
161       getrusage().  For backward compatibility, glibc also provides vtimes().
162       All new applications should be written using getrusage().
163
164       See also the description of /proc/[pid]/stat in proc(5).
165

SEE ALSO

167       clock_gettime(2), getrlimit(2), times(2), wait(2), wait4(2), clock(3)
168

COLOPHON

170       This  page  is  part of release 5.04 of the Linux man-pages project.  A
171       description of the project, information about reporting bugs,  and  the
172       latest     version     of     this    page,    can    be    found    at
173       https://www.kernel.org/doc/man-pages/.
174
175
176
177Linux                             2017-09-15                      GETRUSAGE(2)
Impressum