Setting an Alarm

The alarm and setitimer functions provide a mechanism for a process to interrupt itself at some future time. They do this by setting a timer; when the timer expires, the process receives a signal.

Each process has three independent interval timers available:

• A real-time timer that counts clock time. This timer sends a SIGALRM signal to the process when it expires.
• A virtual timer that counts CPU time used by the process. This timer sends a SIGVTALRM signal to the process when it expires.
• A profiling timer that counts both CPU time used by the process, and CPU time spent in system calls on behalf of the process. This timer sends a 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, and in that case it would be terminated, since that 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.

Data Type: struct itimerval

This structure is used to specify when a timer should expire. It contains the following members:

struct timeval it_interval

This is the interval between successive timer interrupts. If zero, the alarm will only be sent once.

struct timeval it_value

This is the interval to the first timer interrupt. If zero, the alarm is disabled.

The struct timeval data type is described in section High-Resolution Calendar.

Function: int setitimer (int which, struct itimerval *new, struct itimerval *old)

The 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

The timer interval was too large.

Function: int getitimer (int which, struct itimerval *old)

The 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

This constant can be used as the which argument to the setitimer and getitimer functions to specify the real-time timer.

ITIMER_VIRTUAL

This constant can be used as the which argument to the setitimer and getitimer functions to specify the virtual timer.

ITIMER_PROF

This constant can be used as the which argument to the setitimer and getitimer functions to specify the profiling timer.

Function: unsigned int alarm (unsigned int seconds)

The 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.