getitimer()

NAME

getitimer(), setitimer() - get and set value of interval timer

SYNOPSIS

#include <sys/time.h>


int getitimer (int which, struct itimerval *value);
int setitimer (int which, struct itimerval *value,
			 struct itimerval *ovalue);

DESCRIPTION

The getitimer(2) call stores the current value of the which timer into the structure pointed to by value. The setitimer(2) call sets the timer indicated by which to the value stored in the structure value. The previous value of the timer is stored in ovalue, if ovalue is not NULL.

The which argument specifies one of three types of timers (defined in <sys/time.h>):

ITIMER_REAL

The real-time timer decrements in real time. When this timer expires, a SIGALRM signal is delivered to the process.

ITIMER_VIRTUAL

The virtual timer decrements in process virtual (user) time that is, only when the process is executing. When it expires, a SIGVTALRM signal is delivered to the process.

ITIMER_PROF

The profile timer decrements in process virtual (user) time and also when the system is running on behalf of the process. Each time this timer expires, a SIGPROF signal is delivered to the process. This timer is intended for use by interpreters, for statistically profiling the execution of interpreted programs.

The itimerval structure defines a timer value:

struct itimerval {
   struct timeval it_interval;
   struct timeval it_value;
};

The timeval structure is:

struct timeval {
   time_t tv_sec;
   long tv_usec;
};

If the value of it_value is non-zero, it is a time until the next timer expiration. If the value is zero, then getitimer(2) disables a timer when it is called, regardless of the value of it_interval.

If the value of it_interval is non-zero, it is an interval value which will be placed in it_value after the timer expires. If the value is zero, then the timer is disabled after the next time it expires.

The value must be in canonical form: the number of microseconds (tv_usec) must be less than 1,000,000 (a million) and neither the number of seconds (tv_sec) or microseconds (tv_usec) can be negative integers.

Three traditional macros are also defined in <sys/time.h> for setting and testing timer values.

timerclear()

sets a timer value to zero.

timerisset()

tests whether a timer value is zero.

timercmp()

compares two timer values. Warning: do not use inequality operators (<= or >=) with this macro.)

RETURN VALUE

The getitimer(2) utility exits with status 0 for success, and >0 if an error occurred.

ERRORS

The getitimer(2) and setitimer(2) calls can fail for the following reasons:

[EINTR]

The system call was interrupted.

[EINVAL]

The which argument is unknown.

[ENOMEM]

The system could not allocate space for maintaining the timer.

[ENOSYS]

The INTERIX subsystem on the machine is an earlier version than 2.2. (Versions before 2.2 did not support getitimer(2) or setitimer(2).)

The setitimer(2) call can also fail because:

[EINVAL]

The value argument is not in canonical form.

SEE ALSO

alarm(2)

sleep(3)