getitimer() — Get value of an interval timer

Standards

Standards / Extensions	C or C++	Dependencies
XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/time.h>

int getitimer(int which, struct itimerval *value);

General description

getitimer() gets the current value of an (previously set) interval timer. An interval timer is a timer which sends a signal after each repetition (interval) of time.

The which argument indicates what kind of time is being controlled. Values for which are:

ITIMER_REAL: This timer is marking real (clock) time. A SIGALRM signal is generated after each interval of time.
Note: alarm() also sets the real interval timer.
ITIMER_VIRTUAL: This timer is marking process virtual time. Process virtual time is the amount of time spent while executing in the process, and can be thought of as a CPU timer. A SIGVTALRM signal is generated after each interval of time.
ITIMER_PROF: This timer is marking process virtual time plus time spent while the system is running on behalf of the process. A SIGPROF signal is generated after each interval of time.

Note: In a multithreaded environment, each of the above timers is specific to a thread of execution for both the generation of the time interval and the measurement of time. For example, an ITIMER_VIRTUAL timer will mark execution time for just the thread, not the entire process.

The value argument is a pointer to a structure containing:

it_interval: timer interval
it_value: current timer value (time remaining)

Each of these fields is a timeval structure, and contains:

tv_sec: seconds since January 1, 1970 (UTC)
tv_usec: microseconds

Returned value

If successful, getitimer() returns 0, and value points to the itimerval structure.

If unsuccessful, getitimer() returns -1 and sets errno to one of the following values:

Error Code: Description
EINVAL: which is not a valid timer type.