| blob | 8a1615894e62f4e8d0cde0fa07cffe32054d9c33 |
1 '\" te
2 .\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved Portions Copyright
3 .\" (c) 1992, X/Open Company Limited All Rights Reserved
4 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
7 .\" This notice shall appear on any product containing this material.
8 .TH GETRUSAGE 3C "Jul 2, 2004"
9 .SH NAME
10 getrusage \- get information about resource utilization
11 .SH SYNOPSIS
12 .LP
13 .nf
14 #include <sys/resource.h>
16 \fBint\fR \fBgetrusage\fR(\fBint\fR \fIwho\fR, \fBstruct rusage *\fR\fIr_usage\fR);
17 .fi
19 .SH DESCRIPTION
20 .sp
21 .LP
22 The \fBgetrusage()\fR function provides measures of the resources used by the
23 current process, its terminated and waited-for child processes, or the current
24 light weight process (LWP). If the value of the \fIwho\fR argument is
25 \fBRUSAGE_SELF\fR, information is returned about resources used by the current
26 process. If the value of the \fIwho\fR argument is \fBRUSAGE_CHILDREN\fR,
27 information is returned about resources used by the terminated and waited-for
28 children of the current process. If the child is never waited for (for
29 instance, if the parent has \fBSA_NOCLDWAIT\fR set or sets \fBSIGCHLD\fR to
30 \fBSIG_IGN\fR), the resource information for the child process is discarded and
31 not included in the resource information provided by \fBgetrusage()\fR. If the
32 value of the \fIwho\fR argument is \fBRUSAGE_LWP\fR, information is returned
33 about resources used by the current LWP.
34 .sp
35 .LP
36 The \fIr_usage\fR argument is a pointer to an object of type \fBstruct\fR
37 \fBrusage\fR in which the returned information is stored. The members of
38 \fBrusage\fR are as follows:
39 .sp
40 .in +2
41 .nf
42 struct timeval ru_utime; /* user time used */
43 struct timeval ru_stime; /* system time used */
44 long ru_maxrss; /* maximum resident set size */
45 long ru_idrss; /* integral resident set size */
46 long ru_minflt; /* page faults not requiring physical
47 I/O */
48 long ru_majflt; /* page faults requiring physical I/O */
49 long ru_nswap; /* swaps */
50 long ru_inblock; /* block input operations */
51 long ru_oublock; /* block output operations */
52 long ru_msgsnd; /* messages sent */
53 long ru_msgrcv; /* messages received */
54 long ru_nsignals; /* signals received */
55 long ru_nvcsw; /* voluntary context switches */
56 long ru_nivcsw; /* involuntary context switches */
57 .fi
58 .in -2
60 .sp
61 .LP
62 The structure members are interpreted as follows:
63 .sp
64 .ne 2
65 .na
66 \fB\fBru_utime\fR\fR
67 .ad
68 .RS 15n
69 The total amount of time spent executing in user mode. Time is given in seconds
70 and microseconds.
71 .RE
73 .sp
74 .ne 2
75 .na
76 \fB\fBru_stime\fR\fR
77 .ad
78 .RS 15n
79 The total amount of time spent executing in system mode. Time is given in
80 seconds and microseconds.
81 .RE
83 .sp
84 .ne 2
85 .na
86 \fB\fBru_maxrss\fR\fR
87 .ad
88 .RS 15n
89 The maximum resident set size. Size is given in pages (the size of a page, in
90 bytes, is given by the \fBgetpagesize\fR(3C) function). See the \fBNOTES\fR
91 section of this page.
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fBru_idrss\fR\fR
98 .ad
99 .RS 15n
100 An "integral" value indicating the amount of memory in use by a process while
101 the process is running. This value is the sum of the resident set sizes of the
102 process running when a clock tick occurs. The value is given in pages times
103 clock ticks. It does not take sharing into account. See the \fBNOTES\fR
104 section of this page.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fBru_minflt\fR\fR
111 .ad
112 .RS 15n
113 The number of page faults serviced which did not require any physical I/O
114 activity. See the \fBNOTES\fR section of this page.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fBru_majflt\fR\fR
121 .ad
122 .RS 15n
123 The number of page faults serviced which required physical I/O activity. This
124 could include page ahead operations by the kernel. See the \fBNOTES\fR section
125 of this page.
126 .RE
128 .sp
129 .ne 2
130 .na
131 \fB\fBru_nswap\fR\fR
132 .ad
133 .RS 15n
134 The number of times a process was swapped out of main memory.
135 .RE
137 .sp
138 .ne 2
139 .na
140 \fB\fBru_inblock\fR\fR
141 .ad
142 .RS 15n
143 The number of times the file system had to perform input in servicing a
144 \fBread\fR(2) request.
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fBru_oublock\fR\fR
151 .ad
152 .RS 15n
153 The number of times the file system had to perform output in servicing a
154 \fBwrite\fR(2) request.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fBru_msgsnd\fR\fR
161 .ad
162 .RS 15n
163 The number of messages sent over sockets.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBru_msgrcv\fR\fR
170 .ad
171 .RS 15n
172 The number of messages received from sockets.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fBru_nsignals\fR\fR
179 .ad
180 .RS 15n
181 The number of signals delivered.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBru_nvcsw\fR\fR
188 .ad
189 .RS 15n
190 The number of times a context switch resulted due to a process voluntarily
191 giving up the processor before its time slice was completed (usually to await
192 availability of a resource).
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fBru_nivcsw\fR\fR
199 .ad
200 .RS 15n
201 The number of times a context switch resulted due to a higher priority process
202 becoming runnable or because the current process exceeded its time slice.
203 .RE
205 .SH RETURN VALUES
206 .sp
207 .LP
208 Upon successful completion, \fBgetrusage()\fR returns \fB0\fR. Otherwise,
209 \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
210 .SH ERRORS
211 .sp
212 .LP
213 The \fBgetrusage()\fR function will fail if:
214 .sp
215 .ne 2
216 .na
217 \fB\fBEFAULT\fR\fR
218 .ad
219 .RS 10n
220 The address specified by the \fIr_usage\fR argument is not in a valid portion
221 of the process' address space.
222 .RE
224 .sp
225 .ne 2
226 .na
227 \fB\fBEINVAL\fR\fR
228 .ad
229 .RS 10n
230 The \fBwho\fR parameter is not a valid value.
231 .RE
233 .SH ATTRIBUTES
234 .sp
235 .LP
236 See \fBattributes\fR(5) for descriptions of the following attributes:
237 .sp
239 .sp
240 .TS
241 box;
242 l | l
243 l | l .
244 ATTRIBUTE TYPE ATTRIBUTE VALUE
245 _
246 Interface Stability Standard
247 .TE
249 .SH SEE ALSO
250 .sp
251 .LP
252 \fBsar\fR(1M), \fBread\fR(2), \fBtimes\fR(2), \fBwrite\fR(2),
253 \fBgetpagesize\fR(3C), \fBgettimeofday\fR(3C), \fBwait\fR(3C),
254 \fBattributes\fR(5), \fBstandards\fR(5)
255 .SH NOTES
256 .sp
257 .LP
258 The \fBru_maxrss\fR, \fBru_ixrss\fR, \fBru_idrss\fR, and \fBru_isrss\fR members
259 of the \fBrusage\fR structure are set to 0 in this implementation.
260 .sp
261 .LP
262 The numbers \fBru_inblock\fR and \fBru_oublock\fR account only for real I/O,
263 and are approximate measures at best. Data supplied by the cache mechanism is
264 charged only to the first process to read and the last process to write the
265 data.
266 .sp
267 .LP
268 The way resident set size is calculated is an approximation, and could
269 misrepresent the true resident set size.
270 .sp
271 .LP
272 Page faults can be generated from a variety of sources and for a variety of
273 reasons. The customary cause for a page fault is a direct reference by the
274 program to a page which is not in memory. Now, however, the kernel can
275 generate page faults on behalf of the user, for example, servicing
276 \fBread\fR(2) and \fBwrite\fR(2) functions. Also, a page fault can be caused by
277 an absent hardware translation to a page, even though the page is in physical
278 memory.
279 .sp
280 .LP
281 In addition to hardware detected page faults, the kernel may cause pseudo page
282 faults in order to perform some housekeeping. For example, the kernel may
283 generate page faults, even if the pages exist in physical memory, in order to
284 lock down pages involved in a raw I/O request.
285 .sp
286 .LP
287 By definition, major page faults require physical I/O, while minor page faults
288 do not require physical I/O. For example, reclaiming the page from the free
289 list would avoid I/O and generate a minor page fault. More commonly, minor page
290 faults occur during process startup as references to pages which are already in
291 memory. For example, if an address space faults on some "hot" executable or
292 shared library, this results in a minor page fault for the address space. Also,
293 any one doing a \fBread\fR(2) or \fBwrite\fR(2) to something that is in the
294 page cache will get a minor page fault(s) as well.
295 .sp
296 .LP
297 There is no way to obtain information about a child process which has not yet
298 terminated.