Arguments:

The ID of the timer whose expiration date you want to set, as returned by
TimerCreate().

flags

Flags that specify what you want to set for the timer; at most one of the following:

TIMER_ABSTIME — set an absolute expiration time.

TIMER_TOLERANCE — specify the amount of the tolerance to allow the kernel in
low-power situations.

If you don't set either of these bits, the function sets a relative expiration time.
For more information, see below.

If you're setting an expiration time (i.e., you specify TIMER_ABSTIME or neither bit),
you can OR in TIMER_PRECISE to override any default tolerance that was set for
the process (see
procmgr_timer_tolerance()).

itime

A pointer to an _itimer structure that specifies the
expiration date or tolerance, depending on the flag set.
If you specify TIMER_TOLERANCE for the flags argument,
itime can be NULL.

oitime

NULL, or a pointer to an _itimer structure
where the function can store the previous data.

Library:

libc

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

Description:

The TimerSettime() and TimerSettime_r()
kernel calls set the expiration time of the timer specified by id.

These functions are identical except in the way they indicate errors.
See the Returns section for details.

If you specify a flag of TIMER_ABSTIME,
then the nsec member represents an absolute expiration date in nanoseconds
from the Unix Epoch, 00:00:00 January 1, 1970 UTC.
If the date specified has already passed, then the expiration event is delivered immediately.

If you don't specify TIMER_ABSTIME or TIMER_TOLERANCE,
nsec represents a relative expiration period
that's offset from the given clock's current system time, in nanoseconds.

If nsec is zero, then the timer is disarmed.

If interval_nsec is nonzero,
then it specifies a repeat rate which is added to the timer once the nsec period has expired.
Subsequently, the timer is automatically rearmed,
causing it to become repetitive with a period of interval_nsec.

If the timer is already armed when you call TimerSettime(),
this call discards the previous setting and sets a new setting.

If the event notification specified by TimerCreate() has a
sigev_code of SI_TIMER,
then at most one event is queued.
In this case, if an event is pending from a previous timer when the timer fires again, a timer overrun occurs.
You can use the
TimerInfo()
kernel call to obtain the number of overruns that have occurred on this timer.

If the oitime argument isn't NULL, the function fills in the structure
that it points to with the interval timer period (i.e.,
the previous amount of time left before the timer was to have expired),
or zero if the timer was disarmed at the time of the call.
The previous repeat rate is stored in the interval_nsec member.

Timer tolerance

If you specify the TIMER_TOLERANCE flag, then:

If itime isn't NULL, the nsec member specifies the
amount of tolerance, in nanoseconds, that the kernel is allowed in low-power situations.
You can specify a large value (e.g., ~0ULL) for infinite tolerance.
The kernel uses the expiry time plus the tolerance value to decide if it should enter tickless operation
or a low-power mode.

If oitime isn't NULL, the function sets the nsec
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 QNX NeutrinoProgrammer's Guide.

Blocking states

This call doesn't block.

Returns:

The only difference between these functions is the way they indicate errors:

TimerSettime()

If an error occurs, -1 is returned and
errno is set.
Any other value returned indicates success.

TimerSettime_r()

EOK is returned on success. This function does NOT set errno.
If an error occurs, any value in the Errors section may be returned.