setitimer()

Set the value of an interval timer

Synopsis:

#include <sys/time.h>

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

Since:

BlackBerry 10.0.0

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, which includes the following members:

struct timeval    it_interval;    /* timer interval */
struct timeval    it_value;       /* current value */

Each struct timeval contains the following members:

  • time_t tv_sec — the number of seconds since the start of the Unix Epoch.
  • suseconds_t tv_usec — the number of microseconds.

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 Microkernel's Concept of Time chapter of the BlackBerry 10 OS 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

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

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.

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus