TimerSettime(), TimerSettime_r()
Arm a timer with the given expiration time, disarm it, or set its tolerance
Synopsis:
#include <sys/neutrino.h>
int TimerSettime( timer_t id,
int flags,
const struct _itimer * itime,
struct _itimer * oitime );
int TimerSettime_r( timer_t id,
int flags,
const struct _itimer * itime,
struct _itimer * oitime );
Arguments:
- id
- The ID of the timer that you want to modify, 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 — configure how the kernel will treat the expiry time for
this timer. If the itime structure specifies an expiry value less than the
current tick size, the kernel configures a high-resolution timer (HRT). If the value specified
is greater than or equal to the current tick size, the kernel sets a tolerance to allow the
timer to expire at a later time in low-power situations.
As this flag is for setting only how later expiration values will be treated and not the actual expiration value, TIMER_ABSTIME will be ignored if passed in the same call.
If you don't set either of these flags, 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 time or tolerance, depending on the flag settings. If you specify TIMER_TOLERANCE for that other 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() functions either set the expiration time of the timer specified by id, or set the tolerance for that timer, depending on the flags provided.
These functions are identical except in the way they indicate errors. See the Returns section for details.
The _itimer structure contains at least the following members:
- uint64_t nsec
- uint64_t interval_nsec
The meaning of these fields depends on the flags specified.
Expiration date
If you specify the TIMER_ABSTIME flag, then the nsec member represents an absolute expiration date, in nanoseconds from the start of the Unix Epoch, 00:00:00 January 1, 1970 UTC. If the specified date 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, in nanoseconds, from the given clock's system time at the time of this function call. If the source clock is CLOCK_REALTIME, the timer is unaffected by future adjustments to this clock. That is, the timer still expires at the relative time defined in nsec.
In either case, 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.
Understanding the Microkernel's Concept of Timechapter of the QNX Neutrino Programmer's Guide.
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, then the nsec member
determines how the kernel will treat the expiry time for this timer.
You can specify a large value (e.g.,
~0ULL) for infinite tolerance. - If oitime isn't NULL, the function sets the nsec member to the previous tolerance.
(QNX Neutrino 7.0.1 or later) In order to set the tolerance to a value between 0 and the clock period, you need to have the PROCMGR_AID_HIGH_RESOLUTION_TIMER ability enabled. For more information, see procmgr_ability().
You can set the tolerance at any time without affecting the active/inactive status of the timer.
For more information, see
Tolerant and high-resolution timers
in the
Understanding the Microkernel's Concept of Time
chapter of the QNX Neutrino Programmer'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.
Errors:
- EINVAL
- The timer specified by id doesn't exist.
- EFAULT
- A fault occurred when the kernel tried to access itime or oitime.
- EINVAL
- One of the following is true:
- The timer specified by id doesn't exist.
- The timer specified by id was for a CPU-time clock and TIMER_TOLERANCE was passed in flags.
- EOVERFLOW
- The sum of the current time plus the provided relative time results in a value that exceeds UINT64_MAX.
- EPERM
- The calling process doesn't have the required permission; see procmgr_ability().
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Interrupt handler | No |
| Signal handler | Yes |
| Thread | Yes |