The alarm
and setitimer
functions provide a mechanism for a
process to interrupt itself in the future. They do this by setting a
timer; when the timer expires, the process receives a signal.
Each process has three independent interval timers available:
SIGALRM
signal to the process when it expires.
SIGVTALRM
signal to the process when it expires.
SIGPROF
signal to the process when it expires.
This timer is useful for profiling in interpreters. The interval timer
mechanism does not have the fine granularity necessary for profiling
native code.
You can only have one timer of each kind set at any given time. If you set a timer that has not yet expired, that timer is simply reset to the new value.
You should establish a handler for the appropriate alarm signal using
signal
or sigaction
before issuing a call to
setitimer
or alarm
. Otherwise, an unusual chain of events
could cause the timer to expire before your program establishes the
handler. In this case it would be terminated, since termination is the
default action for the alarm signals. See section Signal Handling.
The setitimer
function is the primary means for setting an alarm.
This facility is declared in the header file `sys/time.h'. The
alarm
function, declared in `unistd.h', provides a somewhat
simpler interface for setting the real-time timer.
struct timeval it_interval
struct timeval it_value
The struct timeval
data type is described in section Elapsed Time.
setitimer
function sets the timer specified by which
according to new. The which argument can have a value of
ITIMER_REAL
, ITIMER_VIRTUAL
, or ITIMER_PROF
.
If old is not a null pointer, setitimer
returns information
about any previous unexpired timer of the same kind in the structure it
points to.
The return value is 0
on success and -1
on failure. The
following errno
error conditions are defined for this function:
EINVAL
getitimer
function stores information about the timer specified
by which in the structure pointed at by old.
The return value and error conditions are the same as for setitimer
.
ITIMER_REAL
setitimer
and getitimer
functions to specify the real-time
timer.
ITIMER_VIRTUAL
setitimer
and getitimer
functions to specify the virtual
timer.
ITIMER_PROF
setitimer
and getitimer
functions to specify the profiling
timer.
alarm
function sets the real-time timer to expire in
seconds seconds. If you want to cancel any existing alarm, you
can do this by calling alarm
with a seconds argument of
zero.
The return value indicates how many seconds remain before the previous
alarm would have been sent. If there is no previous alarm, alarm
returns zero.
The alarm
function could be defined in terms of setitimer
like this:
unsigned int alarm (unsigned int seconds) { struct itimerval old, new; new.it_interval.tv_usec = 0; new.it_interval.tv_sec = 0; new.it_value.tv_usec = 0; new.it_value.tv_sec = (long int) seconds; if (setitimer (ITIMER_REAL, &new, &old) < 0) return 0; else return old.it_value.tv_sec; }
There is an example showing the use of the alarm
function in
section Signal Handlers that Return.
If you simply want your process to wait for a given number of seconds,
you should use the sleep
function. See section Sleeping.
You shouldn't count on the signal arriving precisely when the timer expires. In a multiprocessing environment there is typically some amount of delay involved.
Portability Note: The setitimer
and getitimer
functions are derived from BSD Unix, while the alarm
function is
specified by the POSIX.1 standard. setitimer
is more powerful than
alarm
, but alarm
is more widely used.
Go to the first, previous, next, last section, table of contents.