1getrusage(3C) Standard C Library Functions getrusage(3C)
2
6 getrusage - get information about resource utilization
7
9 #include <sys/resource.h>
10 int getrusage(int who, struct rusage *r_usage);
12
15 The getrusage() function provides measures of the resources used by the
16 current process, its terminated and waited-for child processes, or the
17 current light weight process (LWP). If the value of the who argument
18 is RUSAGE_SELF, information is returned about resources used by the
19 current process. If the value of the who argument is RUSAGE_CHILDREN,
20 information is returned about resources used by the terminated and
21 waited-for children of the current process. If the child is never
22 waited for (for instance, if the parent has SA_NOCLDWAIT set or sets
23 SIGCHLD to SIG_IGN), the resource information for the child process is
24 discarded and not included in the resource information provided by
25 getrusage(). If the value of the who argument is RUSAGE_LWP, informa‐
26 tion is returned about resources used by the current LWP.
27 The r_usage argument is a pointer to an object of type struct rusage in
30 which the returned information is stored. The members of rusage are as
31 follows:
32 struct timeval ru_utime; /* user time used */
34 struct timeval ru_stime; /* system time used */
35 long ru_maxrss; /* maximum resident set size */
36 long ru_idrss; /* integral resident set size */
37 long ru_minflt; /* page faults not requiring physical
38 I/O */
39 long ru_majflt; /* page faults requiring physical I/O */
40 long ru_nswap; /* swaps */
41 long ru_inblock; /* block input operations */
42 long ru_oublock; /* block output operations */
43 long ru_msgsnd; /* messages sent */
44 long ru_msgrcv; /* messages received */
45 long ru_nsignals; /* signals received */
46 long ru_nvcsw; /* voluntary context switches */
47 long ru_nivcsw; /* involuntary context switches */
48 The structure members are interpreted as follows:
52 ru_utime The total amount of time spent executing in user mode.
54 Time is given in seconds and microseconds.
55 ru_stime The total amount of time spent executing in system mode.
58 Time is given in seconds and microseconds.
59 ru_maxrss The maximum resident set size. Size is given in pages
62 (the size of a page, in bytes, is given by the getpage‐
63 size(3C) function). See the NOTES section of this page.
64 ru_idrss An "integral" value indicating the amount of memory in
67 use by a process while the process is running. This
68 value is the sum of the resident set sizes of the
69 process running when a clock tick occurs. The value is
70 given in pages times clock ticks. It does not take shar‐
71 ing into account. See the NOTES section of this page.
72 ru_minflt The number of page faults serviced which did not require
75 any physical I/O activity. See the NOTES section of
76 this page.
77 ru_majflt The number of page faults serviced which required physi‐
80 cal I/O activity. This could include page ahead opera‐
81 tions by the kernel. See the NOTES section of this
82 page.
83 ru_nswap The number of times a process was swapped out of main
86 memory.
87 ru_inblock The number of times the file system had to perform input
90 in servicing a read(2) request.
91 ru_oublock The number of times the file system had to perform out‐
94 put in servicing a write(2) request.
95 ru_msgsnd The number of messages sent over sockets.
98 ru_msgrcv The number of messages received from sockets.
101 ru_nsignals The number of signals delivered.
104 ru_nvcsw The number of times a context switch resulted due to a
107 process voluntarily giving up the processor before its
108 time slice was completed (usually to await availability
109 of a resource).
110 ru_nivcsw The number of times a context switch resulted due to a
113 higher priority process becoming runnable or because the
114 current process exceeded its time slice.
115
118 Upon successful completion, getrusage() returns 0. Otherwise, −1 is
119 returned and errno is set to indicate the error.
120
122 The getrusage() function will fail if:
123 EFAULT The address specified by the r_usage argument is not in a
125 valid portion of the process' address space.
126 EINVAL The who parameter is not a valid value.
129
132 See attributes(5) for descriptions of the following attributes:
133 ┌─────────────────────────────┬─────────────────────────────┐
138 │ATTRIBUTE TYPE │ATTRIBUTE VALUE │
139 ├─────────────────────────────┼─────────────────────────────┤
140 │Interface Stability │Standard │
141 └─────────────────────────────┴─────────────────────────────┘
142
144 sar(1M), read(2), times(2), write(2), getpagesize(3C), gettimeof‐
145 day(3C), wait(3C), attributes(5), standards(5)
146
148 The ru_maxrss, ru_ixrss, ru_idrss, and ru_isrss members of the rusage
149 structure are set to 0 in this implementation.
150 The numbers ru_inblock and ru_oublock account only for real I/O, and
153 are approximate measures at best. Data supplied by the cache mechanism
154 is charged only to the first process to read and the last process to
155 write the data.
156 The way resident set size is calculated is an approximation, and could
159 misrepresent the true resident set size.
160 Page faults can be generated from a variety of sources and for a vari‐
163 ety of reasons. The customary cause for a page fault is a direct refer‐
164 ence by the program to a page which is not in memory. Now, however,
165 the kernel can generate page faults on behalf of the user, for example,
166 servicing read(2) and write(2) functions. Also, a page fault can be
167 caused by an absent hardware translation to a page, even though the
168 page is in physical memory.
169 In addition to hardware detected page faults, the kernel may cause
172 pseudo page faults in order to perform some housekeeping. For example,
173 the kernel may generate page faults, even if the pages exist in physi‐
174 cal memory, in order to lock down pages involved in a raw I/O request.
175 By definition, major page faults require physical I/O, while minor page
178 faults do not require physical I/O. For example, reclaiming the page
179 from the free list would avoid I/O and generate a minor page fault.
180 More commonly, minor page faults occur during process startup as refer‐
181 ences to pages which are already in memory. For example, if an address
182 space faults on some "hot" executable or shared library, this results
183 in a minor page fault for the address space. Also, any one doing a
184 read(2) or write(2) to something that is in the page cache will get a
185 minor page fault(s) as well.
186 There is no way to obtain information about a child process which has
189 not yet terminated.
190SunOS 5.11 2 Jul 2004 getrusage(3C)