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

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.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

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.

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.1 Performance Management Guide.