getitimer(2) CLIX getitimer(2)
NAME
getitimer, setitimer - Gets/sets value of an interval timer
LIBRARY
Berkeley Software Distribution Library (libbsd.a)
SYNOPSIS
#include <sys/time.h>
int getitimer(
int which ,
struct itimerval *value );
int setitimer(
int which ,
struct itimerval *value ,
struct itimerval *ovalue );
PARAMETERS
which Identifies the timer to be manipulated.
value Points to a buffer where the current timer value is located.
ovalue Points to the buffer where the old timer value is placed.
DESCRIPTION
The system provides each process with three interval timers, defined in
the <sys/time.h> header file. The getitimer() function returns the
current value for the timer specified in which in the structure at value.
The setitimer() function sets a timer to the specified value (returning
the previous timer value if ovalue is nonzero).
A timer value is defined by the itimerval structure:
struct itimerval {
struct timeval it_interval; /* timer interval */
struct timeval it_value; /* current value */
};
A nonzero it_value indicates the time until the next timer expiration. A
nonzero it_interval 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 disables a timer after its next expiration (assuming
it_value is nonzero).
Time values smaller than the system clock resolution are rounded up to
2/94 - Intergraph Corporation 1
getitimer(2) CLIX getitimer(2)
this resolution (1/60-second interval).
The ITIMER_REAL timer decrements in real time. A SIGALRM signal is
delivered when this timer expires.
The ITIMER_VIRTUAL timer decrements in process virtual time. It runs only
when the process is executing. A SIGVTALRM signal is delivered when this
timer expires.
The ITIMER_PROF timer decrements both in process virtual time and when the
system is running on behalf of the process. It is designed for
interpreters to use 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 functions.
EXAMPLES
1. To get the current value of the REAL interval timer:
getitimer(ITIMER_REAL, &itimerval_buf);
2. To arrange for itimer_hdlr to be invoked after a program has executed
for 10 seconds:
struct itimerval it_buf;
it_buf.it_value.tv_sec = 10;
it_buf.it_value.tv_usec = 0;
it_buf.it_interval.tv_sec = 10;
it_buf.it_interval.tv_usec = 0;
signal(SIGVTALRM, itimer_hdlr);
setitimer(ITIMER_VIRTUAL, &it_buf);
NOTES
Three macros for manipulating time values are defined in <sys/time.h>.
The timerclear() function sets a time value to 0, timerisset() determines
whether a time value is nonzero, and timercmp() compares two time values
(>= and <= do not work with this macro).
RETURN VALUES
Upon successful completion, a value of 0 is returned. Otherwise, a value
of -1 is returned and errno is set to indicate the error.
ERRORS
The getitimer() and setitimer() functions fail if one or more of the
2 Intergraph Corporation - 2/94
getitimer(2) CLIX getitimer(2)
following are true:
[EFAULT] The value parameter specified a bad address.
[EINVAL] A value parameter specified a time too large to be handled.
RELATED INFORMATION
Functions: sigset(2), gettimeofday(2)
2/94 - Intergraph Corporation 3