Next: Sleeping, Previous: Calendar Time, Up: Date and Time
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 Signal Handling.
To be able to use the alarm function to interrupt a system call which
might block otherwise indefinitely it is important to not set the
SA_RESTART flag when registering the signal handler using
sigaction. When not using sigaction things get even
uglier: the signal function has to fixed semantics with respect
to restarts. The BSD semantics for this function is to set the flag.
Therefore, if sigaction for whatever reason cannot be used, it is
necessary to use sysv_signal and not signal.
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.
This structure is used to specify when a timer should expire. It contains the following members:
struct timeval it_interval- This is the period between successive timer interrupts. If zero, the alarm will only be sent once.
struct timeval it_value- This is the period between now and the first timer interrupt. If zero, the alarm is disabled.
The
struct timevaldata type is described in Elapsed Time.
The
setitimerfunction sets the timer specified by which according to new. The which argument can have a value ofITIMER_REAL,ITIMER_VIRTUAL, orITIMER_PROF.If old is not a null pointer,
setitimerreturns information about any previous unexpired timer of the same kind in the structure it points to.The return value is
0on success and-1on failure. The followingerrnoerror conditions are defined for this function:
EINVAL- The timer period is too large.
The
getitimerfunction 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_REALsetitimer and getitimer functions to specify the real-time
timer.
ITIMER_VIRTUALsetitimer and getitimer functions to specify the virtual
timer.
ITIMER_PROFsetitimer and getitimer functions to specify the profiling
timer.
The
alarmfunction sets the real-time timer to expire in seconds seconds. If you want to cancel any existing alarm, you can do this by callingalarmwith 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,
alarmreturns 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
Handler Returns.
If you simply want your process to wait for a given number of seconds,
you should use the sleep function. See 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.