setitimer()

Set the value of an interval timer

Synopsis:

#include <sys/time.h>

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

Library:

libc

Description:

The system provides each process with interval timers, defined in <sys/time.h>. The setitimer() function sets the value of the timer specified by which to the value specified in the structure pointed to by value, and if ovalue isn't NULL, stores the previous value of the timer in the structure it points to.

A timer value is defined by the itimerval structure (see gettimeofday() 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 nonzero).

Time values smaller than the resolution of the system clock are rounded up to the resolution of the system clock.

The only supported timer is ITIMER_REAL, which decrements in real time. A SIGALRM signal is delivered when this timer expires.

The SIGALRM so generated isn't maskable on this bound thread by any signal-masking function, pthread_sigmask(), or sigprocmask().

Returns:

0

Success.

-1

An error occurred; errno is set.

Errors:

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.

Classification:

Standard Unix

Caveats:

All flags to setitimer() other than ITIMER_REAL behave as documented only with "bound" threads. Their ability to mask the signal works only with bound threads. If the call is made using one of these flags from an unbound thread, the system call returns -1 and sets errno to EACCES.

These behaviors are the same for bound or unbound POSIX threads. A POSIX thread with system-wide scope, created by the call:

pthread_attr_setscope(&attr, PTHREAD_SCOPE_SYSTEM);

is equivalent to a Solaris bound thread. A POSIX thread with local process scope, created by the call:

pthread_attr_setscope(&attr, PTHREAD_SCOPE_PROCESS);

is equivalent to a Solaris unbound thread.

The microseconds field shouldn't be equal to or greater than one second.

The setitimer() function is independent of alarm().

Don't use setitimer(ITIMER_REAL) with the sleep() routine. A sleep() call wipes out knowledge of the user signal handler for SIGALRM.

The granularity of the resolution of alarm time is platform-dependent.

See also:

alarm(), getitimer(), gettimeofday(), pthread_attr_setscope(), pthread_sigmask(), sigprocmask(), sleep(), sysconf()