1getrusage(3C)            Standard C Library Functions            getrusage(3C)
2
3
4

NAME

6       getrusage - get information about resource utilization
7

SYNOPSIS

9       #include <sys/resource.h>
10
11       int getrusage(int who, struct rusage *r_usage);
12
13

DESCRIPTION

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
28
29       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
33         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
49
50
51       The structure members are interpreted as follows:
52
53       ru_utime       The total amount of time spent executing in  user  mode.
54                      Time is given in seconds and microseconds.
55
56
57       ru_stime       The total amount of time spent executing in system mode.
58                      Time is given in seconds and microseconds.
59
60
61       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
65
66       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
73
74       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
78
79       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
84
85       ru_nswap       The number of times a process was swapped  out  of  main
86                      memory.
87
88
89       ru_inblock     The number of times the file system had to perform input
90                      in servicing a read(2) request.
91
92
93       ru_oublock     The number of times the file system had to perform  out‐
94                      put in servicing a write(2) request.
95
96
97       ru_msgsnd      The number of messages sent over sockets.
98
99
100       ru_msgrcv      The number of messages received from sockets.
101
102
103       ru_nsignals    The number of signals delivered.
104
105
106       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
111
112       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
116

RETURN VALUES

118       Upon successful completion, getrusage() returns  0.  Otherwise,  −1  is
119       returned and errno is set to indicate the error.
120

ERRORS

122       The  getrusage() function will fail if:
123
124       EFAULT    The  address  specified  by  the r_usage argument is not in a
125                 valid portion of the process' address space.
126
127
128       EINVAL    The who parameter is not a valid value.
129
130

ATTRIBUTES

132       See attributes(5) for descriptions of the following attributes:
133
134
135
136
137       ┌─────────────────────────────┬─────────────────────────────┐
138       │ATTRIBUTE TYPE               │ATTRIBUTE VALUE              │
139       ├─────────────────────────────┼─────────────────────────────┤
140       │Interface Stability          │Standard                     │
141       └─────────────────────────────┴─────────────────────────────┘
142

SEE ALSO

144       sar(1M),  read(2),  times(2),  write(2),  getpagesize(3C),   gettimeof‐
145       day(3C), wait(3C), attributes(5), standards(5)
146

NOTES

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
151
152       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
157
158       The  way resident set size is calculated is an approximation, and could
159       misrepresent the true resident set size.
160
161
162       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
170
171       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
176
177       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
187
188       There  is  no way to obtain information about a child process which has
189       not yet terminated.
190
191
192
193SunOS 5.11                        2 Jul 2004                     getrusage(3C)
Impressum