TimerAlarm(), TimerAlarm

Schedule a SIGALRM for delivery

Synopsis:

#include <sys/neutrino.h>

int TimerAlarm( clockid_t id,
                const struct _itimer * itime,
                struct _itimer * otime );

int TimerAlarm_r( clockid_t id,
                  const struct _itimer * itime,
                  struct _itimer * otime );

Arguments:

id

The timer type to use to implement the alarm; one of:

CLOCK_REALTIME — the standard POSIX-defined clock. Timers based on this clock wake up the processor if it's in a power-saving mode.
CLOCK_SOFTTIME — (a QNX Neutrino extension) this clock is active only when the processor isn't in a power-saving mode. For example, an application using a CLOCK_SOFTTIME timer to sleep wouldn't wake up the processor when the application was due to wake up. This will allow the processor to enter a power-saving mode.
While the processor isn't in a power-saving mode, CLOCK_SOFTTIME behaves the same as CLOCK_REALTIME.
CLOCK_MONOTONIC — this clock always increases at a constant rate and can't be adjusted.

For more information about the different clocks, see “Other clock sources” in the Clocks, Timers, and Getting a Kick Every So Often of Getting Started with QNX Neutrino.

itime

NULL, or a pointer to an _itimer structure that specifies the length of time to wait (see below).

otime

NULL, or a pointer to an _itimer structure where the function can store the old trigger time.

Library:

libc

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

Description:

These kernel calls activate an internal timer to schedule an alarm signal (SIGALRM) for delivery to the thread waiting on the timer. The signal will be delivered at the time specified by itime. If otime isn't NULL, the old trigger time is written into this structure.

The TimerAlarm() and TimerAlarm_r() functions are identical except in the way they indicate errors. See the Returns section for details.

Note:

Instead of using these kernel calls directly, consider calling alarm() or setitimer().
Because of the nature of time measurement, the signal might actually get sent later than the specified time. For more information, see the “Understanding the Microkernel's Concept of Time” chapter of the QNX Neutrino Programmer's Guide.

The _itimer structure contains at least the following members:

uint64_t nsec — the number of nanoseconds to wait, or 0 to cancel any previous request for an alarm.
uint64_t interval_nsec — 0, or a repeat rate that's added to the timer once the nsec period has expired. Subsequently, the timer is automatically rearmed, causing it to repeat with a period of interval_nsec.

Alarm requests aren't stacked; only a single SIGALRM may be outstanding on a timer at one time. If you call TimerAlarm() while an alarm is outstanding, the alarm is reset to the new value passed in itime.

If itime is 0, the function returns right away. If it's NULL, the function doesn't schedule any signal and just reads the remaining time into otime (assuming it's non-NULL).

Blocking states

These calls don't block.

Returns:

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

TimerAlarm(): If an error occurs, -1 is returned and errno is set. Any other value returned indicates success.
TimerAlarm_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:

EAGAIN: All kernel timer entries are in use.
EINVAL: Invalid timer value id.

Classification:

QNX Neutrino

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

Caveats:

The alarm(), TimerAlarm(), and ualarm() requests aren't stacked; only a single SIGALRM can be scheduled with these functions. If the SIGALRM signal hasn't been generated, the next call to alarm(), TimerAlarm(), or ualarm() reschedules it.

TimerAlarm(), TimerAlarm_r()