GETITIMER(2) System Calls GETITIMER(2)
NAME
getitimer, setitimer - get or set value of interval timer
SYNOPSIS
#include <sys/time.h>
int getitimer(
int which,
struct itimerval *value);
int setitimer(
int which,
const struct itimerval *value,
struct itimerval *ovalue);
DESCRIPTION
The system provides each process with four interval timers, defined
in <
sys/time.h>. The
getitimer() function stores the current value of
the timer specified by
which into the structure pointed to by
value.
The
setitimer() function 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(3C)) for the definition of
timeval), which includes the
following members:
struct timeval it_interval; /* timer interval */
struct timeval it_value; /* current value */
The
it_value member indicates the time to the next timer expiration.
The
it_interval member specifies a value to be used in reloading
it_value when the timer expires. Setting
it_value to 0 disables a
timer, regardless of the value of
it_interval. Setting
it_interval to
0 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 the resolution of the system clock, except for
ITIMER_REALPROF, whose values are rounded up to the resolution of the
profiling clock. The four timers are as follows:
ITIMER_REAL Decrements in real time. A
SIGALRM signal is
delivered to the process when this timer expires.
ITIMER_VIRTUAL Decrements in lightweight process (lwp) virtual
time. It runs only when the calling lwp is
executing. A
SIGVTALRM signal is delivered to the
calling lwp when it expires.
ITIMER_PROF Decrements both in lightweight process (lwp)
virtual time and when the system is running on
behalf of the lwp. 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 to the calling lwp. Because this signal
may interrupt in-progress functions, programs
using this timer must be prepared to restart
interrupted functions.
ITIMER_REALPROF Decrements in real time. It is designed to be used
for real-time profiling of multithreaded programs.
Each time the
ITIMER_REALPROF timer expires, one
counter in a set of counters maintained by the
system for each lightweight process (lwp) is
incremented. The counter corresponds to the state
of the lwp at the time of the timer tick. All lwps
executing in user mode when the timer expires are
interrupted into system mode. When each lwp
resumes execution in user mode, if any of the
elements in its set of counters are non-zero, the
SIGPROF signal is delivered to the lwp. The
SIGPROF signal is delivered before any other
signal except
SIGKILL. This signal does not
interrupt any in-progress function. A
siginfo structure, defined in
<sys/siginfo.h>, is
associated with the delivery of the
SIGPROF signal, and includes the following members:
si_tstamp; /* high resolution timestamp */
si_syscall; /* current syscall */
si_nsysarg; /* number of syscall arguments */
si_sysarg[]; /* actual syscall arguments */
si_fault; /* last fault type */
si_faddr; /* last fault address */
si_mstate[]; /* ticks in each microstate */
The enumeration of microstates (indices into
si_mstate) is defined in
<sys/msacct.h>.
Unlike the other interval timers, the
ITIMER_REALPROF interval timer is not inherited
across a call to one of the
exec(2) family of
functions.
RETURN VALUES
Upon successful completion,
0 is returned. Otherwise,
-1 is returned
and
errno is set to indicate the error.
ERRORS
The
getitimer() and
setitimer() functions will fail if:
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 argument is unrecognized.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
alarm(2),
exec(2),
gettimeofday(3C),
sleep(3C),
sysconf(3C),
attributes(7),
standards(7)NOTES
The
setitimer() function is independent of the
alarm(2) and
sleep(3C) functions.
The
ITIMER_PROF and
ITIMER_REALPROF timers deliver the same signal
and have different semantics. They cannot be used together.
The granularity of the resolution of alarm time is platform-
dependent.
June 15, 2009 GETITIMER(2)
