[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
getrusage, getrusage64, times, or vtimes Subroutine
Purpose
Displays information about resource use.
Libraries
getrusage, getrusage64, times: Standard C Library (libc.a)
vtimes: |
Berkeley Compatibility Library (libbsd.a) |
Syntax
#include <sys/times.h>
#include <sys/resource.h>
int getrusage ( Who, RUsage)
int Who;
struct rusage *RUsage;
int getrusage64 ( Who, RUsage)
int Who;
struct rusage64 *RUsage;
#include <sys/types.h>
#include <sys/times.h>
clock_t times ( Buffer)
struct tms *Buffer;
#include <sys/times.h>
vtimes ( ParentVM, ChildVM)
struct vtimes *ParentVm, ChildVm;
Description
The getrusage subroutine displays
information about how resources are used by the current process or all completed
child processes.
When compiled in 64-bit mode, rusage counters are
64 bits. If getrusage is compiled in 32-bit mode, rusage counters are 32 bits. If the kernel's value of
a usage counter has exceeded the capacity of the corresponding
32-bit rusage value being returned, the rusage value is set to INT_MAX.
The getrusage64 subroutine can be called to make
64-bit rusage counters explicitly available in a 32-bit
environment.
In AIX 5.1 and later, 64-bit quantities are also available to 64-bit
applications through the getrusage() interface in the
ru_utime and ru_stime fields of struct rusage.
The times subroutine fills the
structure pointed to by the Buffer parameter with
time-accounting information. All time values reported by the times subroutine are measured in terms of the number of clock ticks
used. Applications should use sysconf (_SC_CLK_TCK) to determine the number of clock ticks per second.
The tms structure defined in
the /usr/include/sys/times.h file contains the following
fields:
time_t tms_utime;
time_t tms_stime;
time_t tms_cutime;
time_t tms_cstime;
This information is read from the calling process
as well as from each completed child process for which the calling process
executed a wait subroutine.
tms_utime |
The CPU time used for executing instructions in the user space of
the calling process |
tms_stime |
The CPU time used by the system on behalf of the calling process. |
tms_cutime |
The sum of the tms_utime and the tms_cutime values for all the child processes. |
tms_cstime |
The sum of the tms_stime and the tms_cstime values for all the child processes. |
Note
The system measures time by counting clock interrupts. The
precision of the values reported by the times subroutine
depends on the rate at which the clock interrupts occur.
The vtimes subroutine is supported
to provide compatibility with earlier programs.
The vtimes subroutine returns
accounting information for the current process and for the completed child
processes of the current process. Either the ParentVm parameter, the ChildVm parameter, or both may
be 0. In that case, only the information for the nonzero pointers is returned.
After a call to the vtimes subroutine,
each buffer contains information as defined by the contents of the /usr/include/sys/vtimes.h file.
Parameters
Who |
Specifies a value of RUSAGE_THREAD, RUSAGE_SELF, or RUSAGE_CHILDREN. |
RUsage |
Points to a buffer described in the /usr/include/sys/resource.h file. The fields are interpreted as follows:
- ru_utime
- The total amount of time running in user mode.
- ru_stime
- The total amount of time spent in the system executing on behalf of
the processes.
- ru_maxrss
- The maximum size, in kilobytes, of the used resident set size.
- ru_ixrss
- An integral value indicating the amount of memory used by the text
segment that was also shared among other processes. This value is expressed
in units of kilobytes * seconds-of-execution and is calculated by adding
the number of shared memory pages in use each time the internal system clock
ticks, and then averaging over one-second intervals.
- ru_idrss
- An integral value of the amount of unshared memory in the data segment
of a process (expressed in units of kilobytes * seconds-of-execution).
- ru_minflt
- The number of page faults serviced without any I/O activity. In this
case, I/O activity is avoided by reclaiming a page frame from the list of
pages awaiting reallocation.
- ru_majflt
- The number of page faults serviced that required I/O activity.
- ru_nswap
- The number of times a process was swapped out of main memory.
- ru_inblock
- The number of times the file system performed input.
- ru_oublock
- The number of times the file system performed output.
Note
The numbers that the ru_inblock and ru_oublock fields display account for real I/O only; data supplied
by the caching mechanism is charged only to the first process to read or
write the data.
- ru_msgsnd
- The number of IPC messages sent.
- ru_msgrcv
- The number of IPC messages received.
- ru_nsignals
- The number of signals delivered.
- ru_nvcsw
- The number of times a context switch resulted because a process voluntarily
gave up the processor before its time slice was completed. This usually
occurs while the process waits for availability of a resource.
- ru_nivcsw
- The number of times a context switch resulted because a higher priority
process ran or because the current process exceeded its time slice.
|
Buffer |
Points to a tms structure. |
ParentVm |
Points to a vtimes structure that contains
the accounting information for the current process. |
ChildVm |
Points to a vtimes structure that contains
the accounting information for the terminated child processes of the current
process. |
Return Values
Upon successful completion, the getrusage and getrusage64 subroutines return a
value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.
Upon successful completion, the times subroutine returns the elapsed real time in units of ticks, whether
profiling is enabled or disabled. This reference time does not change from
one call of the times subroutine to another. If the times subroutine fails, it returns a value of -1 and sets
the errno global variable to indicate the error.
Error Codes
The getrusage and getrusage64 subroutines do not run successfully
if either of the following is true: |
EINVAL |
The Who parameter is not a valid value. |
EFAULT |
The address specified for RUsage is not valid. |
The times subroutine does not run successfully if the following is true: |
EFAULT |
The address specified by the buffer parameter
is not valid. |
Related Information
The gettimer, settimer, restimer, stime, or time (gettimer, settimer, restimer, stime, or time Subroutine) subroutine, wait, waitpid, or wait3 subroutine.
Performance-Related Subroutines in AIX 5L Version 5.2 Performance Management Guide.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]