getitimer, setitimer — get or set value of an interval timer
#include <sys/time.h>
int
getitimer( |
int | which, |
struct itimerval * | value) ; |
int
setitimer( |
int | which, |
const struct itimerval * | value, | |
struct itimerval * | ovalue) ; |
The system provides each process with three interval timers, each decrementing in a distinct time domain. When any timer expires, a signal is sent to the process, and the timer (potentially) restarts.
ITIMER_REAL
decrements in real time, and delivers SIGALRM
upon expiration.
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 profile the time spent by the application in
user and kernel 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 indicated by value
with the current setting
for the timer indicated 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 indicated timer to the
value in value
. If
ovalue
is non-zero,
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. (But see BUGS
below.) Upon expiration, 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
loading.
On success, zero is returned. On error, −1 is
returned, and errno
is set
appropriately.
value
or
ovalue
are not
valid pointers.
which
is not
one of ITIMER_REAL
,
ITIMER_VIRTUAL
, or
ITIMER_PROF
.
A child created via fork(2) does not inherit its parent's interval timers. Interval timers are preserved across an execve(2).
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 process. 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, 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/x86 (where, since kernel 2.6.13, the default jiffy
is 0.004 seconds), this means that the ceiling value for a
timer is approximately 99.42 days.
On certain systems (including x86), 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, Linux does
not give an error, but instead silently adjusts the
corresponding seconds value for the timer. In the future
(scheduled for March 2007), this non-conformance will be
repaired: existing applications should be fixed now to ensure
that they supply a properly formed tv_usec
value.
gettimeofday(2), sigaction(2), signal(2), time(7)
Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us> Based on a similar page Copyright 1992 by Rick Faith May be freely distributed Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se> Noted MAX_SEC_IN_JIFFIES ceiling |