getitimer(3C) getitimer(3C)
NAME
getitimer, setitimer - get/set 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.
Copyright 1994 Novell, Inc. Page 1
getitimer(3C) getitimer(3C)
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.
Copyright 1994 Novell, Inc. Page 2
getitimer(3C) getitimer(3C)
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.
Copyright 1994 Novell, Inc. Page 3