1.\" Copyright (c) 1985, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)getrusage.2 8.1 (Berkeley) 6/4/93
| 1.\" Copyright (c) 1985, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)getrusage.2 8.1 (Berkeley) 6/4/93
|
34.\"
35.Dd June 4, 1993
36.Dt GETRUSAGE 2
37.Os
38.Sh NAME
39.Nm getrusage
40.Nd get information about resource utilization
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/types.h
45.In sys/time.h
46.In sys/resource.h
47.Fd "#define RUSAGE_SELF 0"
48.Fd "#define RUSAGE_CHILDREN -1"
49.Ft int
50.Fn getrusage "int who" "struct rusage *rusage"
51.Sh DESCRIPTION
52The
53.Fn getrusage
54system call
55returns information describing the resources utilized by the current
56process, or all its terminated child processes.
57The
58.Fa who
59argument is either
60.Dv RUSAGE_SELF
61or
62.Dv RUSAGE_CHILDREN .
63The buffer to which
64.Fa rusage
65points will be filled in with
66the following structure:
67.Bd -literal
68struct rusage {
69 struct timeval ru_utime; /* user time used */
70 struct timeval ru_stime; /* system time used */
71 long ru_maxrss; /* max resident set size */
72 long ru_ixrss; /* integral shared text memory size */
73 long ru_idrss; /* integral unshared data size */
74 long ru_isrss; /* integral unshared stack size */
75 long ru_minflt; /* page reclaims */
76 long ru_majflt; /* page faults */
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};
86.Ed
87.Pp
88The fields are interpreted as follows:
89.Bl -tag -width ru_minfltaa
90.It Fa ru_utime
91the total amount of time spent executing in user mode.
92.It Fa ru_stime
93the total amount of time spent in the system executing on behalf
94of the process(es).
95.It Fa ru_maxrss
96the maximum resident set size utilized (in kilobytes).
97.It Fa ru_ixrss
98an
99.Dq integral
100value indicating the amount of memory used
101by the text segment
| 34.\"
35.Dd June 4, 1993
36.Dt GETRUSAGE 2
37.Os
38.Sh NAME
39.Nm getrusage
40.Nd get information about resource utilization
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/types.h
45.In sys/time.h
46.In sys/resource.h
47.Fd "#define RUSAGE_SELF 0"
48.Fd "#define RUSAGE_CHILDREN -1"
49.Ft int
50.Fn getrusage "int who" "struct rusage *rusage"
51.Sh DESCRIPTION
52The
53.Fn getrusage
54system call
55returns information describing the resources utilized by the current
56process, or all its terminated child processes.
57The
58.Fa who
59argument is either
60.Dv RUSAGE_SELF
61or
62.Dv RUSAGE_CHILDREN .
63The buffer to which
64.Fa rusage
65points will be filled in with
66the following structure:
67.Bd -literal
68struct rusage {
69 struct timeval ru_utime; /* user time used */
70 struct timeval ru_stime; /* system time used */
71 long ru_maxrss; /* max resident set size */
72 long ru_ixrss; /* integral shared text memory size */
73 long ru_idrss; /* integral unshared data size */
74 long ru_isrss; /* integral unshared stack size */
75 long ru_minflt; /* page reclaims */
76 long ru_majflt; /* page faults */
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};
86.Ed
87.Pp
88The fields are interpreted as follows:
89.Bl -tag -width ru_minfltaa
90.It Fa ru_utime
91the total amount of time spent executing in user mode.
92.It Fa ru_stime
93the total amount of time spent in the system executing on behalf
94of the process(es).
95.It Fa ru_maxrss
96the maximum resident set size utilized (in kilobytes).
97.It Fa ru_ixrss
98an
99.Dq integral
100value indicating the amount of memory used
101by the text segment
|
103in units of kilobytes * ticks-of-execution.
104Ticks are statistics clock ticks.
105The statistics clock has a frequency of
106.Fn sysconf _SC_CLOCK_TCK
107ticks per second.
108.It Fa ru_idrss
109an integral value of the amount of unshared memory residing in the
110data segment of a process (expressed in units of
111kilobytes * ticks-of-execution).
112.It Fa ru_isrss
113an integral value of the amount of unshared memory residing in the
114stack segment of a process (expressed in units of
115kilobytes * ticks-of-execution).
116.It Fa ru_minflt
117the number of page faults serviced without any I/O activity; here
118I/O activity is avoided by
119.Dq reclaiming
120a page frame from
121the list of pages awaiting reallocation.
122.It Fa ru_majflt
123the number of page faults serviced that required I/O activity.
124.It Fa ru_nswap
125the number of times a process was
126.Dq swapped
127out of main
128memory.
129.It Fa ru_inblock
130the number of times the file system had to perform input.
131.It Fa ru_oublock
132the number of times the file system had to perform output.
133.It Fa ru_msgsnd
134the number of IPC messages sent.
135.It Fa ru_msgrcv
136the number of IPC messages received.
137.It Fa ru_nsignals
138the number of signals delivered.
139.It Fa ru_nvcsw
140the number of times a context switch resulted due to a process
141voluntarily giving up the processor before its time slice was
142completed (usually to await availability of a resource).
143.It Fa ru_nivcsw
144the number of times a context switch resulted due to a higher
145priority process becoming runnable or because the current process
146exceeded its time slice.
147.El
148.Sh NOTES
149The numbers
150.Fa ru_inblock
151and
152.Fa ru_oublock
153account only for real
154I/O; data supplied by the caching mechanism is charged only
155to the first process to read or write the data.
156.Sh RETURN VALUES
157.Rv -std getrusage
158.Sh ERRORS
159The
160.Fn getrusage
161system call will fail if:
162.Bl -tag -width Er
163.It Bq Er EINVAL
164The
165.Fa who
166argument is not a valid value.
167.It Bq Er EFAULT
168The address specified by the
169.Fa rusage
170argument is not in a valid part of the process address space.
171.El
172.Sh SEE ALSO
173.Xr gettimeofday 2 ,
174.Xr wait 2 ,
175.Xr clocks 7
176.Sh BUGS
177There is no way to obtain information about a child process
178that has not yet terminated.
179.Sh HISTORY
180The
181.Fn getrusage
182system call appeared in
183.Bx 4.2 .
| 104in units of kilobytes * ticks-of-execution.
105Ticks are statistics clock ticks.
106The statistics clock has a frequency of
107.Fn sysconf _SC_CLOCK_TCK
108ticks per second.
109.It Fa ru_idrss
110an integral value of the amount of unshared memory residing in the
111data segment of a process (expressed in units of
112kilobytes * ticks-of-execution).
113.It Fa ru_isrss
114an integral value of the amount of unshared memory residing in the
115stack segment of a process (expressed in units of
116kilobytes * ticks-of-execution).
117.It Fa ru_minflt
118the number of page faults serviced without any I/O activity; here
119I/O activity is avoided by
120.Dq reclaiming
121a page frame from
122the list of pages awaiting reallocation.
123.It Fa ru_majflt
124the number of page faults serviced that required I/O activity.
125.It Fa ru_nswap
126the number of times a process was
127.Dq swapped
128out of main
129memory.
130.It Fa ru_inblock
131the number of times the file system had to perform input.
132.It Fa ru_oublock
133the number of times the file system had to perform output.
134.It Fa ru_msgsnd
135the number of IPC messages sent.
136.It Fa ru_msgrcv
137the number of IPC messages received.
138.It Fa ru_nsignals
139the number of signals delivered.
140.It Fa ru_nvcsw
141the number of times a context switch resulted due to a process
142voluntarily giving up the processor before its time slice was
143completed (usually to await availability of a resource).
144.It Fa ru_nivcsw
145the number of times a context switch resulted due to a higher
146priority process becoming runnable or because the current process
147exceeded its time slice.
148.El
149.Sh NOTES
150The numbers
151.Fa ru_inblock
152and
153.Fa ru_oublock
154account only for real
155I/O; data supplied by the caching mechanism is charged only
156to the first process to read or write the data.
157.Sh RETURN VALUES
158.Rv -std getrusage
159.Sh ERRORS
160The
161.Fn getrusage
162system call will fail if:
163.Bl -tag -width Er
164.It Bq Er EINVAL
165The
166.Fa who
167argument is not a valid value.
168.It Bq Er EFAULT
169The address specified by the
170.Fa rusage
171argument is not in a valid part of the process address space.
172.El
173.Sh SEE ALSO
174.Xr gettimeofday 2 ,
175.Xr wait 2 ,
176.Xr clocks 7
177.Sh BUGS
178There is no way to obtain information about a child process
179that has not yet terminated.
180.Sh HISTORY
181The
182.Fn getrusage
183system call appeared in
184.Bx 4.2 .
|