GETITIMER(2) Linux Programmer s Manual GETITIMER(2)

NAME getitimer, setitimer - get or set value of an interval timer

SYNOPSIS #include <sys/time.h>

int getitimer(int which, struct itimerval *curr_value); int setitimer(int which, const struct itimerval *new_value, struct itimerval *old_value);

DESCRIPTION The system provides each process with three interval timers, each decrementing in a distinct time domain. When any timer expires, a sig- nal is sent to the process, and the timer (potentially) restarts.

ITIMER_REAL decrements in real time, and delivers SIGALRM upon expi- ration.

ITIMER_VIRTUAL decrements only when the process is executing, and delivers SIGVTALRM upon expiration.

ITIMER_PROF decrements both when the process executes and when the system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL, this timer is usually used to pro- file the time spent by the application in user and ker- nel space. SIGPROF is delivered upon expiration.

Timer values are defined by the following structures:

struct itimerval { struct timeval it_interval; /* next value */ struct timeval it_value; /* current value */ };

struct timeval { long tv_sec; /* seconds */ long tv_usec; /* microseconds */ };

The function getitimer() fills the structure pointed to by curr_value with the current setting for the timer specified by which (one of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF). The element it_value is set to the amount of time remaining on the timer, or zero if the timer is disabled. Similarly, it_interval is set to the reset value.

The function setitimer() sets the specified timer to the value in new_value. If old_value is non-NULL, the old value of the timer is stored there.

Timers decrement from it_value to zero, generate a signal, and reset to it_interval. A timer which is set to zero (it_value is zero or the timer expires and it_interval is zero) stops.

Both tv_sec and tv_usec are significant in determining the duration of a timer.

Timers will never expire before the requested time, but may expire some (short) time afterwards, which depends on the system timer resolution and on the system load; see time(7). (But see BUGS below.) Upon expi- ration, a signal will be generated and the timer reset. If the timer expires while the process is active (always true for ITIMER_VIRTUAL) the signal will be delivered immediately when generated. Otherwise the delivery will be offset by a small time dependent on the system load- ing.

RETURN VALUE On success, zero is returned. On error, -1 is returned, and errno is set appropriately.

ERRORS EFAULT new_value, old_value, or curr_value is not valid a pointer.

EINVAL which is not one of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF; or (since Linux 2.6.22) one of the tv_usec fields in the struc- ture pointed to by new_value contains a value outside the range 0 to 999999.

CONFORMING TO POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). POSIX.1-2008 marks getitimer() and setitimer() obsolete, recommending the use of the POSIX timers API (timer_gettime(2), timer_settime(2), etc.) instead.

NOTES A child created via fork(2) does not inherit its parents interval timers. Interval timers are preserved across an execve(2).

POSIX.1 leaves the interaction between setitimer() and the three inter- faces alarm(2), sleep(3), and usleep(3) unspecified.

BUGS The generation and delivery of a signal are distinct, and only one instance of each of the signals listed above may be pending for a pro- cess. Under very heavy loading, an ITIMER_REAL timer may expire before the signal from a previous expiration has been delivered. The second signal in such an event will be lost.

On Linux kernels before 2.6.16, timer values are represented in jiffies. If a request is made set a timer with a value whose jiffies representation exceeds MAX_SEC_IN_JIFFIES (defined in include/linux/jiffies.h), then the timer is silently truncated to this ceiling value. On Linux/i386 (where, since Linux 2.6.13, the default jiffy is 0.004 seconds), this means that the ceiling value for a timer is approximately 99.42 days. Since Linux 2.6.16, the kernel uses a different internal representation for times, and this ceiling is removed.

On certain systems (including i386), Linux kernels before version 2.6.12 have a bug which will produce premature timer expirations of up to one jiffy under some circumstances. This bug is fixed in kernel 2.6.12.

POSIX.1-2001 says that setitimer() should fail if a tv_usec value is specified that is outside of the range 0 to 999999. However, in ker- nels up to and including 2.6.21, Linux does not give an error, but instead silently adjusts the corresponding seconds value for the timer. From kernel 2.6.22 onwards, this non-conformance has been repaired: an improper tv_usec value results in an EINVAL error.

SEE ALSO gettimeofday(2), sigaction(2), signal(2), timer_create(2), timerfd_cre- ate(2), time(7)

COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.

Linux 2009-03-15 GETITIMER(2)