getitimer(3C)

getitimer -- get value of interval timer

Synopsis

   #include <sys/time.h>
   
   int getitimer(int which, struct itimerval value);
   

   int setitimer(int which, struct itimerval value,
   	struct itimerval ovalue);

Description

The system provides each process with three interval timers, defined in sys/time.h. The getitimer call stores the current value of the timer specified by which into the structure pointed to by value. The setitimer call sets the value of the timer specified by which to the value specified in the structure pointed to by value, and if ovalue is not NULL, stores the previous value of the timer in the structure pointed to by ovalue.

A timer value is defined by the itimerval structure [see gettimeofday(2) for the definition of timeval], which includes the following members:

   struct timeval	it_interval;	/ timer interval /
   struct timeval	it_value;		/ current value /

If it_value is non-zero, it indicates the time to the next timer expiration. If it_interval is non-zero, it specifies a value to be used in reloading it_value when the timer expires. Setting it_value to zero disables a timer, regardless of the value of it_interval. Setting it_interval to zero disables a timer after its next expiration (assuming it_value is non-zero).

Time values smaller than the resolution of the system clock are rounded up to this resolution.

The three timers are:

ITIMER_REAL: Decrements in real time. A SIGALRM signal is delivered when this timer expires.
ITIMER_VIRTUAL: Decrements in process virtual time. It runs only when the process is executing. A SIGVTALRM signal is delivered when it expires.
ITIMER_PROF: Decrements both in process virtual time and when the system is running on behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. Each time the ITIMER_PROF timer expires, the SIGPROF signal is delivered. Because this signal may interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls.

Return values

If the calls succeed, a value of 0 is returned. If an error occurs, the value -1 is returned, and an error code is placed in the global variable errno.

Errors

Under the following conditions, the functions getitimer and setitimer fail and set errno to:

EINVAL: The specified number of seconds is greater than 100,000,000, the number of microseconds is greater than or equal to 1,000,000, or the which parameter is unrecognized.

References

alarm(2), gettimeofday(2)

Notices

The microseconds field should not be equal to or greater than one second.

setitimer is independent of the alarm system call.

Do not use setitimer with the sleep routine. A sleep following a setitimer wipes out knowledge of the user signal handler.

Considerations for threads programming

There is a separate interval timer per thread and the subsequent signal is delivered to the requesting thread; however, only the real time variant (ITIMER_REAL) is supported.

Considerations for lightweight processes

The kernel maintains separate timers per LWP. The SIGALARM, SIGVTALRM and SIGPROF are posted to the individual LWP that set the timers. The Threads Library has ``wrapper'' functions for getitimer and setitimer that direct actions to the correct thread.