timer_settime()

Set the expiration time for a timer

Synopsis:

#include <time.h>

int timer_settime( timer_t timerid,
                   int flags,
                   const struct itimerspec * value,
                   struct itimerspec * ovalue );

Since:

BlackBerry 10.0.0

Arguments:

timerid
A timer_t object that holds a timer ID, as set by timer_create().
flags
The type of timer to arm if you aren't disarming the timer. The valid bits include:
  • TIMER_ABSTIME — the it_value represents an absolute expiration date in seconds and nanoseconds from 1970. If the date specified has already passed, the function succeeds and the expiration notice is made.

    If you don't set this bit, the it_value represents a relative expiration period that's offset from the current system time by the specified number of seconds and nanoseconds.

The following are BlackBerry 10 OS extensions:

  • TIMER_TOLERANCE — specify the amount of the tolerance to allow the kernel in low-power situations. You can't set this and TIMER_ABSTIME in the same call.
  • TIMER_PRECISE — exclude the timer from timer harmonization. You can OR this into the flags if you're setting an expiration time (i.e., you didn't specify TIMER_TOLERANCE).
value
A pointer to a itimerspec structure that specifies the value that you want to set for the timer's time until expiry, or the timer tolerance, depending on the flags. For more information about this structure, see timer_gettime().

If you specify the TIMER_TOLERANCE flag, this argument can be NULL.

ovalue
NULL, or a pointer to a itimerspec structure that the function fills in with the timer's former time until expiry or tolerance, depending on the flags.

Library:

libc

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

Description:

The timer_settime() function sets the expiration time of the timer specified by timerid from the it_value member of the value argument. If the it_value structure member of value is zero, then the timer is disarmed.

The timer_settime() function rounds up time values that are between two consecutive nonnegative integer multiples of the resolution of the specified timer to the larger multiple of the resolution.

If the it_interval member of value is nonzero, then it specifies a repeat rate that is added to the timer once the it_value period has expired. Subsequently, the timer is automatically rearmed, causing it to become continuous with a period of it_interval.

If the ovalue parameter isn't NULL, then on return from this function it contains a value representing the previous amount of time left before the timer was to have expired, or zero if the timer was disarmed. The previous interval timer period is also stored in the it_interval member.

The timerid is local to the calling process, and must have been created using timer_create().

Because of the nature of time measurement, the timer might actually expire after 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.

Timer tolerance

As a BlackBerry 10 OS extension, if you specify the TIMER_TOLERANCE flag, then:

  • If value isn't NULL, the it_value member specifies the amount of tolerance, in nanoseconds, that the kernel is allowed in low-power situations. The kernel uses the expiry time plus the tolerance value to decide if it should enter tickless operation or a low-power mode.
  • If ovalue isn't NULL, the function sets the it_value member to the previous tolerance.

You can set the tolerance at any time without affecting the active/inactive status of the timer. For more information, see " Clocks, timers, and power management " in 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:

EFAULT
A fault occurred trying to access the buffers provided.
EINVAL
The timer timerid isn't attached to the calling process or the number of nanoseconds specified by the tv_nsec member of one of the timespec structures in the itimerspec structure pointed to by value is less than zero or greater than or equal to 1000 million.

Examples:

See timer_create().

Classification:

POSIX 1003.1 TMR

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

Last modified: 2014-06-24



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

comments powered by Disqus