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