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)