setitimer() — Set value of an interval timer
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 | both | POSIX(ON) |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/time.h>
int setitimer(int which, struct itimerval *value, struct itimerval *ovalue);
General description
setitimer() sets the value of an interval timer. An interval timer is a timer which sends a signal after each repetition (interval) of time.
- ITIMER_REAL
- This timer
is marking real (clock) time. A SIGALRM signal is generated after
each interval of time. Note: alarm() also sets the real interval timer.
- ITIMER_VIRTUAL
- This timer is marking process virtual time. Process virtual time is the amount of time spent while executing in the process, and can be thought of as a CPU timer. A SIGVTALRM signal is generated after each interval of time.
- ITIMER_PROF
- This timer is marking process virtual time plus time spent while the system is running on behalf of the process. A SIGPROF signal is generated after each interval of time.
- it_interval
- timer interval
When it_interval is nonzero, it is used as the value which it_value is initialized to after each timer expiration. If it_interval is zero, the timer is disabled after the next expiration, subject to the value in it_value.
- it_value
- current timer value to be set
When it_value is nonzero, it is used as the initial value to establish the timer with, that is, the time to the next timer expiration. If it_value is zero, the timer is immediately disabled.
- it_interval
- current timer interval
- it_value
- current timer value
- tv_sec
- seconds since January 1, 1970 Coordinated Universal Time (UTC)
- tv_usec
- microseconds
Returned value
If successful, setitimer() returns 0, and if ovalue was non-NULL, ovalue points to the itimerval structure containing the old timer values.
- Error Code
- Description
- EINVAL
- which is not a valid timer type, or the value argument has an incorrect (noncanonical) form. The tv_seconds field must be a nonnegative integer, and the tv_usec field must be a nonnegative integer in the range of 0-1,000,000.
Usage of the ITIMER_PROF timer generates a SIGPROF signal which may interrupt an in-progress function. Thus, programs using this timer may need to be able to restart an interrupted function.