Debian Codegraph @

upstream/debian-unstable/man2/getrusage.2

raw
1 '\" t
2 .\" Copyright 1992, Drew Eckhardt <[email protected]>
3 .\" Copyright 2002, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH getrusage 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 getrusage \- get resource usage
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/resource.h>
17 .P
18 .BI "int getrusage(int " who ", struct rusage *" usage );
19 .fi
20 .SH DESCRIPTION
21 .BR getrusage ()
22 returns resource usage measures for
23 .IR who ,
24 which can be one of the following:
25 .TP
26 .B RUSAGE_SELF
27 Return resource usage statistics for the calling process,
28 which is the sum of resources used by all threads in the process.
29 .TP
30 .B RUSAGE_CHILDREN
31 Return resource usage statistics for all children of the
32 calling process that have terminated and been waited for.
33 These statistics will include the resources used by grandchildren,
34 and further removed descendants,
35 if all of the intervening descendants waited on their terminated children.
36 .TP
37 .BR RUSAGE_THREAD " (since Linux 2.6.26)"
38 Return resource usage statistics for the calling thread.
39 The
40 .B _GNU_SOURCE
41 feature test macro must be defined (before including
42 .I any
43 header file)
44 in order to obtain the definition of this constant from
45 .IR <sys/resource.h> .
46 .P
47 The resource usages are returned in the structure pointed to by
48 .IR usage ,
49 which has the following form:
50 .P
51 .in +4n
52 .EX
53 struct rusage {
54 struct timeval ru_utime; /* user CPU time used */
55 struct timeval ru_stime; /* system CPU time used */
56 long ru_maxrss; /* maximum resident set size */
57 long ru_ixrss; /* integral shared memory size */
58 long ru_idrss; /* integral unshared data size */
59 long ru_isrss; /* integral unshared stack size */
60 long ru_minflt; /* page reclaims (soft page faults) */
61 long ru_majflt; /* page faults (hard page faults) */
62 long ru_nswap; /* swaps */
63 long ru_inblock; /* block input operations */
64 long ru_oublock; /* block output operations */
65 long ru_msgsnd; /* IPC messages sent */
66 long ru_msgrcv; /* IPC messages received */
67 long ru_nsignals; /* signals received */
68 long ru_nvcsw; /* voluntary context switches */
69 long ru_nivcsw; /* involuntary context switches */
70 };
71 .EE
72 .in
73 .P
74 Not all fields are completed;
75 unmaintained fields are set to zero by the kernel.
76 (The unmaintained fields are provided for compatibility with other systems,
77 and because they may one day be supported on Linux.)
78 The fields are interpreted as follows:
79 .TP
80 .I ru_utime
81 This is the total amount of time spent executing in user mode,
82 expressed in a
83 .I timeval
84 structure (seconds plus microseconds).
85 .TP
86 .I ru_stime
87 This is the total amount of time spent executing in kernel mode,
88 expressed in a
89 .I timeval
90 structure (seconds plus microseconds).
91 .TP
92 .IR ru_maxrss " (since Linux 2.6.32)"
93 This is the maximum resident set size used (in KiB).
94 For
95 .BR RUSAGE_CHILDREN ,
96 this is the resident set size of the largest child, not the maximum
97 resident set size of the process tree.
98 .TP
99 .IR ru_ixrss " (unmaintained)"
100 This field is currently unused on Linux.
101 .\" On some systems,
102 .\" this is the integral of the text segment memory consumption,
103 .\" expressed in kilobyte-seconds.
104 .TP
105 .IR ru_idrss " (unmaintained)"
106 This field is currently unused on Linux.
107 .\" On some systems, this is the integral of the data segment memory consumption,
108 .\" expressed in kilobyte-seconds.
109 .TP
110 .IR ru_isrss " (unmaintained)"
111 This field is currently unused on Linux.
112 .\" On some systems, this is the integral of the stack memory consumption,
113 .\" expressed in kilobyte-seconds.
114 .TP
115 .I ru_minflt
116 The number of page faults serviced without any I/O activity;
117 here,
118 I/O activity is avoided by \*(lqreclaiming\*(rq a page frame from
119 the list of pages awaiting reallocation.
120 .TP
121 .I ru_majflt
122 The number of page faults serviced that required I/O activity.
123 .TP
124 .IR ru_nswap " (unmaintained)"
125 This field is currently unused on Linux.
126 .\" On some systems, this is the number of swaps out of physical memory.
127 .TP
128 .IR ru_inblock " (since Linux 2.6.22)"
129 The number of times the filesystem had to perform input.
130 .TP
131 .IR ru_oublock " (since Linux 2.6.22)"
132 The number of times the filesystem had to perform output.
133 .TP
134 .IR ru_msgsnd " (unmaintained)"
135 This field is currently unused on Linux.
136 .\" On FreeBSD 6.2, this appears to measure messages sent over sockets
137 .\" On some systems,
138 .\" this field records the number of messages sent over sockets.
139 .TP
140 .IR ru_msgrcv " (unmaintained)"
141 This field is currently unused on Linux.
142 .\" On FreeBSD 6.2, this appears to measure messages received over sockets
143 .\" On some systems,
144 .\" this field records the number of messages received over sockets.
145 .TP
146 .IR ru_nsignals " (unmaintained)"
147 This field is currently unused on Linux.
148 .\" On some systems, this field records the number of signals received.
149 .TP
150 .IR ru_nvcsw " (since Linux 2.6)"
151 The number of times a context switch resulted due to a process
152 voluntarily giving up the processor before its time slice was
153 completed (usually to await availability of a resource).
154 .TP
155 .IR ru_nivcsw " (since Linux 2.6)"
156 The number of times a context switch resulted due to a higher
157 priority process becoming runnable or because the current process
158 exceeded its time slice.
159 .SH RETURN VALUE
160 On success, zero is returned.
161 On error, \-1 is returned, and
162 .I errno
163 is set to indicate the error.
164 .SH ERRORS
165 .TP
166 .B EFAULT
167 .I usage
168 points outside the accessible address space.
169 .TP
170 .B EINVAL
171 .I who
172 is invalid.
173 .SH ATTRIBUTES
174 For an explanation of the terms used in this section, see
175 .BR attributes (7).
176 .TS
177 allbox;
178 lbx lb lb
179 l l l.
180 Interface Attribute Value
181 T{
182 .na
183 .nh
184 .BR getrusage ()
185 T} Thread safety MT-Safe
186 .TE
187 .SH STANDARDS
188 POSIX.1-2024.
189 .P
190 POSIX.1 specifies
191 .BR getrusage (),
192 but specifies only the fields
193 .I ru_utime
194 and
195 .IR ru_stime .
196 .P
197 .B RUSAGE_THREAD
198 is Linux-specific.
199 .SH HISTORY
200 4.3BSD,
201 SVr4,
202 SUSv1,
203 POSIX.1-2001 XSI.
204 .P
205 Before Linux 2.6.9, if the disposition of
206 .B SIGCHLD
207 is set to
208 .B SIG_IGN
209 then the resource usages of child processes
210 are automatically included in the value returned by
211 .BR RUSAGE_CHILDREN ,
212 although POSIX.1-2001 explicitly prohibits this.
213 This nonconformance is rectified in Linux 2.6.9 and later.
214 .\" See the description of getrusage() in XSH.
215 .\" A similar statement was also in SUSv2.
216 .P
217 The structure definition shown at the start of this page
218 was taken from 4.3BSD Reno.
219 .P
220 Ancient systems provided a
221 .BR vtimes ()
222 function with a similar purpose to
223 .BR getrusage ().
224 For backward compatibility, glibc (up until Linux 2.32) also provides
225 .BR vtimes ().
226 All new applications should be written using
227 .BR getrusage ().
228 (Since Linux 2.33, glibc no longer provides an
229 .BR vtimes ()
230 implementation.)
231 .SH NOTES
232 Resource usage metrics are preserved across an
233 .BR execve (2).
234 .SH SEE ALSO
235 .BR clock_gettime (2),
236 .BR getrlimit (2),
237 .BR times (2),
238 .BR wait (2),
239 .BR wait4 (2),
240 .BR clock (3),
241 .BR proc_pid_stat (5),
242 .BR proc_pid_io (5)