getrusage, getrusage64, times, or vtimes Subroutine

Purpose

Displays information about resource use.

Libraries

getrusage, getrusage64, times: Standard C Library (libc.a)

Item Description
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.

Item Description
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

Item Description
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:
Item Description
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:
Item Description
EFAULT The address specified by the buffer parameter is not valid.