[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, 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.

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 either 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 subroutine, wait, waitpid, or wait3 subroutine.

Performance-Related Subroutines in AIX Versions 3.2 and 4 Performance Tuning Guide.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]