]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man2/getrusage.2
getrlimit.2: ATTRIBUTES: Note functions that are thread-safe
[thirdparty/man-pages.git] / man2 / getrusage.2
CommitLineData
e3a887db 1.\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992
6883b3e7 2.\" and Copyright (c) 2002 Michael Kerrisk
e3a887db 3.\"
93015253 4.\" %%%LICENSE_START(VERBATIM)
e3a887db
MK
5.\" Permission is granted to make and distribute verbatim copies of this
6.\" manual provided the copyright notice and this permission notice are
7.\" preserved on all copies.
8.\"
9.\" Permission is granted to copy and distribute modified versions of this
10.\" manual under the conditions for verbatim copying, provided that the
11.\" entire resulting derived work is distributed under the terms of a
12.\" permission notice identical to this one.
c13182ef 13.\"
e3a887db
MK
14.\" Since the Linux kernel and libraries are constantly changing, this
15.\" manual page may be incorrect or out-of-date. The author(s) assume no
16.\" responsibility for errors or omissions, or for damages resulting from
17.\" the use of the information contained herein. The author(s) may not
18.\" have taken the same level of care in the production of this manual,
19.\" which is licensed free of charge, as they might when working
20.\" professionally.
c13182ef 21.\"
e3a887db
MK
22.\" Formatted or processed versions of this manual, if unaccompanied by
23.\" the source, must acknowledge the copyright and authors of this work.
4b72fb64 24.\" %%%LICENSE_END
e3a887db 25.\"
c13182ef
MK
26.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formerly included
27.\" coverage of getrusage(2), has been split, so that the latter is
28.\" now covered in its own getrusage.2. For older details of change
0967c11f 29.\" history, etc., see getrlimit.2
e3a887db 30.\"
cfea5132 31.\" Modified 2004-11-16, mtk, Noted that the nonconformance
e3a887db 32.\" when SIGCHLD is being ignored is fixed in 2.6.9.
94ce95ef
MK
33.\" 2008-02-22, Sripathi Kodi <sripathik@in.ibm.com>: Document RUSAGE_THREAD
34.\" 2008-05-25, mtk, clarify RUSAGE_CHILDREN + other clean-ups.
e3f4bf3e
MK
35.\" 2010-05-24, Mark Hills <mark@pogo.org.uk>: Description of fields,
36.\" document ru_maxrss
57440a98 37.\" 2010-05-24, mtk, enhanced description of various fields
e3a887db 38.\"
726663fd 39.TH GETRUSAGE 2 2014-05-10 "Linux" "Linux Programmer's Manual"
e3a887db
MK
40.SH NAME
41getrusage \- get resource usage
42.SH SYNOPSIS
43.B #include <sys/time.h>
44.br
45.B #include <sys/resource.h>
46.sp
47.BI "int getrusage(int " who ", struct rusage *" usage );
48.SH DESCRIPTION
49.PP
50.BR getrusage ()
94ce95ef
MK
51returns resource usage measures for
52.IR who ,
53which can be one of the following:
54.TP
2914a14d
MK
55.B RUSAGE_SELF
56Return resource usage statistics for the calling process,
94ce95ef
MK
57which is the sum of resources used by all threads in the process.
58.TP
2914a14d 59.B RUSAGE_CHILDREN
94ce95ef
MK
60Return resource usage statistics for all children of the
61calling process that have terminated and been waited for.
62These statistics will include the resources used by grandchildren,
63and further removed descendants,
64if all of the intervening descendants waited on their terminated children.
65.TP
66.BR RUSAGE_THREAD " (since Linux 2.6.26)"
67Return resource usage statistics for the calling thread.
1205c845
MK
68The
69.B _GNU_SOURCE
70feature test macro must be defined (before including
71.I any
72header file)
73in order to obtain the definition of this constant from
74.IR <sys/resource.h> .
94ce95ef
MK
75.PP
76The resource usages are returned in the structure pointed to by
77.IR usage ,
78which has the following form:
c13182ef 79.PP
a08ea57c 80.in +4n
e3a887db
MK
81.nf
82struct rusage {
57440a98
MK
83 struct timeval ru_utime; /* user CPU time used */
84 struct timeval ru_stime; /* system CPU time used */
e3a887db
MK
85 long ru_maxrss; /* maximum resident set size */
86 long ru_ixrss; /* integral shared memory size */
87 long ru_idrss; /* integral unshared data size */
88 long ru_isrss; /* integral unshared stack size */
57440a98
MK
89 long ru_minflt; /* page reclaims (soft page faults) */
90 long ru_majflt; /* page faults (hard page faults) */
e3a887db
MK
91 long ru_nswap; /* swaps */
92 long ru_inblock; /* block input operations */
93 long ru_oublock; /* block output operations */
57440a98
MK
94 long ru_msgsnd; /* IPC messages sent */
95 long ru_msgrcv; /* IPC messages received */
e3a887db
MK
96 long ru_nsignals; /* signals received */
97 long ru_nvcsw; /* voluntary context switches */
98 long ru_nivcsw; /* involuntary context switches */
99};
100.fi
a08ea57c 101.in
d1cd1e05 102.PP
14f1e036
MK
103Not all fields are completed;
104unmaintained fields are set to zero by the kernel.
105(The unmaintained fields are provided for compatibility with other systems,
106and because they may one day be supported on Linux.)
107The fields are interpreted as follows:
d1cd1e05
MH
108.TP
109.I ru_utime
57440a98
MK
110This is the total amount of time spent executing in user mode,
111expressed in a
112.I timeval
113structure (seconds plus microseconds).
d1cd1e05
MH
114.TP
115.I ru_stime
57440a98
MK
116This is the total amount of time spent executing in kernel mode,
117expressed in a
118.I timeval
119structure (seconds plus microseconds).
d1cd1e05 120.TP
c90ccb4e 121.IR ru_maxrss " (since Linux 2.6.32)"
e3948c69
MK
122This is the maximum resident set size used (in kilobytes).
123For
57440a98 124.BR RUSAGE_CHILDREN ,
c90ccb4e
MH
125this is the resident set size of the largest child, not the maximum
126resident set size of the process tree.
d1cd1e05
MH
127.TP
128.IR ru_ixrss " (unmaintained)"
14f1e036
MK
129This field is currently unused on Linux.
130.\" On some systems,
131.\" this is the integral of the text segment memory consumption,
132.\" expressed in kilobyte-seconds.
d1cd1e05
MH
133.TP
134.IR ru_idrss " (unmaintained)"
14f1e036
MK
135This field is currently unused on Linux.
136.\" On some systems, this is the integral of the data segment memory consumption,
137.\" expressed in kilobyte-seconds.
d1cd1e05
MH
138.TP
139.IR ru_isrss " (unmaintained)"
14f1e036
MK
140This field is currently unused on Linux.
141.\" On some systems, this is the integral of the stack memory consumption,
142.\" expressed in kilobyte-seconds.
d1cd1e05
MH
143.TP
144.I ru_minflt
57440a98 145The number of page faults serviced without any I/O activity; here
d1cd1e05
MH
146I/O activity is avoided by \*(lqreclaiming\*(rq a page frame from
147the list of pages awaiting reallocation.
148.TP
149.I ru_majflt
57440a98 150The number of page faults serviced that required I/O activity.
d1cd1e05
MH
151.TP
152.IR ru_nswap " (unmaintained)"
14f1e036
MK
153This field is currently unused on Linux.
154.\" On some systems, this is the number of swaps out of physical memory.
d1cd1e05
MH
155.TP
156.IR ru_inblock " (since Linux 2.6.22)"
9ee4a2b6 157The number of times the filesystem had to perform input.
d1cd1e05
MH
158.TP
159.IR ru_oublock " (since Linux 2.6.22)"
9ee4a2b6 160The number of times the filesystem had to perform output.
d1cd1e05
MH
161.TP
162.IR ru_msgsnd " (unmaintained)"
14f1e036 163This field is currently unused on Linux.
87f8e275 164.\" On FreeBSD 6.2, this appears to measure messages sent over sockets
14f1e036
MK
165.\" On some systems,
166.\" this field records the number of messages sent over sockets.
d1cd1e05
MH
167.TP
168.IR ru_msgrcv " (unmaintained)"
14f1e036 169This field is currently unused on Linux.
87f8e275 170.\" On FreeBSD 6.2, this appears to measure messages received over sockets
14f1e036
MK
171.\" On some systems,
172.\" this field records the number of messages received over sockets.
d1cd1e05
MH
173.TP
174.IR ru_nsignals " (unmaintained)"
14f1e036
MK
175This field is currently unused on Linux.
176.\" On some systems, this field records the number of signals received.
d1cd1e05
MH
177.TP
178.IR ru_nvcsw " (since Linux 2.6)"
57440a98 179The number of times a context switch resulted due to a process
d1cd1e05
MH
180voluntarily giving up the processor before its time slice was
181completed (usually to await availability of a resource).
182.TP
183.IR ru_nivcsw " (since Linux 2.6)"
57440a98 184The number of times a context switch resulted due to a higher
d1cd1e05
MH
185priority process becoming runnable or because the current process
186exceeded its time slice.
187.PP
47297adb 188.SH RETURN VALUE
c13182ef
MK
189On success, zero is returned.
190On error, \-1 is returned, and
e3a887db
MK
191.I errno
192is set appropriately.
193.SH ERRORS
194.TP
195.B EFAULT
196.I usage
197points outside the accessible address space.
198.TP
199.B EINVAL
200.I who
201is invalid.
47297adb 202.SH CONFORMING TO
c13182ef
MK
203SVr4, 4.3BSD.
204POSIX.1-2001 specifies
97c1eac8 205.BR getrusage (),
33a0ccb2 206but specifies only the fields
97c1eac8
MK
207.I ru_utime
208and
209.IR ru_stime .
94ce95ef
MK
210
211.B RUSAGE_THREAD
212is Linux-specific.
e3a887db 213.SH NOTES
dfcc37a6
MK
214Resource usage metrics are preserved across an
215.BR execve (2).
216
e3a887db
MK
217Including
218.I <sys/time.h>
219is not required these days, but increases portability.
220(Indeed,
221.I struct timeval
222is defined in
223.IR <sys/time.h> .)
224.PP
225In Linux kernel versions before 2.6.9, if the disposition of
226.B SIGCHLD
227is set to
228.B SIG_IGN
229then the resource usages of child processes
230are automatically included in the value returned by
231.BR RUSAGE_CHILDREN ,
97c1eac8 232although POSIX.1-2001 explicitly prohibits this.
cfea5132 233This nonconformance is rectified in Linux 2.6.9 and later.
e3a887db
MK
234.\" See the description of getrusage() in XSH.
235.\" A similar statement was also in SUSv2.
236.LP
bc5ec131
MK
237The structure definition shown at the start of this page
238was taken from 4.3BSD Reno.
94ce95ef 239
8a18a944
MK
240Ancient systems provided a
241.BR vtimes ()
242function with a similar purpose to
243.BR getrusage ().
244For backward compatibility, glibc also provides
245.BR vtimes ().
246All new applications should be written using
247.BR getrusage ().
248
94ce95ef
MK
249See also the description of
250.IR /proc/PID/stat
251in
252.BR proc (5).
47297adb 253.SH SEE ALSO
0eb44391 254.BR clock_gettime (2),
e3a887db
MK
255.BR getrlimit (2),
256.BR times (2),
257.BR wait (2),
0302f101 258.BR wait4 (2),
0eb44391 259.BR clock (3)