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.
The
which argument
indicates what kind of time is being controlled. Values for
which are:
- 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.
Note: In a multithreaded environment, each of
the above timers is specific to a thread of execution for both the
generation of the time interval and the measurement of time. For
example, an a ITIMER_VIRTUAL timer will mark execution time for just
the thread, not the entire process.
The
value argument
points to an
itimerval structure containing the timer
value to be set. The structure contains:
- 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.
The
ovalue argument
points to an
itimerval structure in which the current
value of the timer is returned. If
ovalue is
a NULL pointer, the current timer value is not returned. The structure
contains:
- it_interval
- current timer interval
- it_value
- current timer value
For both
itimerval structures,
each of the fields (
it_interval and
it_value)
is a
timeval structure, and contains:
- 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.
If unsuccessful, setitimer() returns -1 and sets errno
to one of the following 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.