setitimer()

Set the value of an interval timer

Synopsis:

#include <sys/time.h>

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

Arguments:

which

The interval time whose value you want to set. Currently, this must be ITIMER_REAL.

value

A pointer to a itimerval structure that specifies the value that you want to set the interval timer to.

ovalue

NULL, or a pointer to a itimerval structure where the function can store the old value of the interval timer.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

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().

---

Because of the nature of time measurement, the timer might actually expire later than the specified time. For more information, see the Tick, Tock: Understanding the Neutrino Microkernel's Concept of Time chapter of the QNX Neutrino Programmer's Guide.

---

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:

POSIX 1003.1 XSI

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 the alarm time is platform-dependent.

See also:

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

Tick, Tock: Understanding the Neutrino Microkernel's Concept of Time chapter of the QNX Neutrino Programmer's Guide