NAME
getitimer,
setitimer —
get/set value of interval timer
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/time.h>
int
getitimer(
int
which,
struct itimerval
*value);
int
setitimer(
int
which,
const struct
itimerval * restrict value,
struct itimerval * restrict
ovalue);
DESCRIPTION
The system provides each process with three interval timers, defined in
⟨
sys/time.h⟩. The
getitimer() call returns the current value for the timer
specified in
which in the structure at
value. The
setitimer() call sets a
timer to the specified
value, returning the previous
value of the timer if
ovalue is not
NULL
.
A timer value is defined by the
itimerval structure:
struct itimerval {
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 0 disables a
timer. Setting
it_interval to 0 causes a timer to be
disabled after its next expiration (assuming
it_value is
non-zero).
The
which parameter specifies the type of the timer:
-
-
ITIMER_REAL
- timer decrements in real time. This timer is affected by
adjtime(2) and
settimeofday(2). A
SIGALRM
signal is delivered when this timer
expires.
-
-
ITIMER_VIRTUAL
- timer decrements in process virtual time. It runs only when
the process is executing. A
SIGVTALRM
signal is
delivered when it expires.
-
-
ITIMER_PROF
- timer 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.
-
-
ITIMER_MONOTONIC
- timer decrements in monotonic time. This timer is not
affected by adjtime(2) and
settimeofday(2). A
SIGALRM
signal is delivered when this timer
expires.
Note that:
- Time values smaller than the resolution of the system
clock are rounded up to this resolution (typically 10 milliseconds).
- The interaction between setitimer()
and alarm(3) or
sleep(3) is unspecified by
the specification.
RETURN VALUES
If the calls succeed, a value of 0 is returned. If an error occurs, the value -1
is returned, and a more precise error code is placed in the global variable
errno.
ERRORS
Both functions may fail if:
-
-
- [
EFAULT
]
- The value parameter specified a bad
address.
-
-
- [
EINVAL
]
- The which parameter was not a known
timer type, or the value parameter specified a time
that was too large to be handled.
SEE ALSO
gettimeofday(2),
select(2),
sigaction(2),
itimerval(3),
timeradd(3)
STANDARDS
The functions conform to
IEEE Std 1003.1-2001
(“POSIX.1”). The later
IEEE Std
1003.1-2008 (“POSIX.1”) revision however marked both as
obsolescent, recommending the use of
timer_gettime(2) and
timer_settime(2) instead.
HISTORY
The
getitimer() function call appeared in
4.2BSD. The
ITIMER_MONOTONIC
functionality appeared in
NetBSD 6.0.