TimerCreate(), TimerCreate_r()

Create a timer for a process

Synopsis:

#include <sys/neutrino.h>

int TimerCreate( clockid_t id,
                 const struct sigevent *event );

int TimerCreate_r( clockid_t id,
                   const struct sigevent *event );

Arguments:

id

The timing base; supported types are:

• CLOCK_REALTIME -- This is the standard POSIX-defined clock. Timers based on this clock should will wake up the processor if it's in a power-saving mode.
• CLOCK_SOFTTIME -- This clock is only active when the processor is not 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.

event

A pointer to a sigevent structure that contains the event to deliver when the timer fires; see below.

Library:

libc

Description:

The TimerCreate() kernel call creates a per-process timer using the clock specified by id as the timing base.

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

Use the returned timer ID in subsequent calls to the other timer functions.

The timer is created in the disabled state, and isn't enabled until you call TimerSettime().

The sigevent structure pointed to by event contains the event to deliver when the timer fires. We recommend the following event types in this case:

• If your process executes in a loop using MsgReceivev(), then SIGEV_PULSE is a convenient way of receiving timer pulses.
• If you use signals for event notification, note that signals are always delivered to the process and not directly to the thread that created or armed the timer. You can change this by using a sigev_notify of SIGEV_SIGNAL_THREAD.
• The notify types of SIGEV_UNBLOCK and SIGEV_INTR, while allowed, are of questionable use with timers. SIGEV_UNBLOCK is typically used by the TimerTimeout() kernel call, and SIGEV_INTR is typically used with the InterruptWait() kernel call.

Blocking states

These calls don't block.

Returns:

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

TimerCreate()

The timer ID of the newly created timer. If an error occurs, -1 is returned and errno is set.

TimerCreate_r()

The timer ID of the newly created timer. This function does NOT set errno. If an error occurs, the negative of a value from the Errors section is returned.

Errors:

EINVAL

The clock ID isn't valid.

EAGAIN

All kernel timer objects are in use.

EFAULT

A fault occurred when the kernel tried to access the buffers provided.

Classification:

QNX 6

See also:

sigevent, TimerAlarm(), TimerDestroy(), TimerInfo(), TimerSettime(), TimerTimeout()