(libc.info.gz) Setting an Alarm

Info Catalog

(libc.info.gz) Calendar Time

(libc.info.gz) Date and Time

(libc.info.gz) Sleeping

 
 21.5 Setting an Alarm
 =====================
 
 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:
 
    * A real-time timer that counts elapsed time.  This timer sends a
      `SIGALRM' signal to the process when it expires.  
 
    * A virtual timer that counts processor time used by the process.
      This timer sends a `SIGVTALRM' signal to the process when it
      expires.  
 
    * A profiling timer that counts both processor time used by the
      process, and processor 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.  In this case it
 would be terminated, since termination is the default action for the
 alarm signals.   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.  
 
  -- 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 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 timeval' data type is described in  Elapsed
      Time.
 
  -- 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 period is 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 
 Handler Returns.
 
    If you simply want your process to wait for a given number of
 seconds, you should use the `sleep' function.   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.
 

Info Catalog

(libc.info.gz) Calendar Time

(libc.info.gz) Date and Time

(libc.info.gz) Sleeping