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 — 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.
  • (QNX Neutrino 7.0.1 or later) CLOCK_THREAD_CPUTIME_ID or a thread CPU-time clock ID returned by pthread_getcpuclockid() or ClockId(). The timeout that you set for this type of timer represents the thread's execution time. CLOCK_THREAD_CPUTIME_ID is a special clock ID that refers to the calling thread. See Monitoring execution times in the “Understanding the Microkernel's Concept of Time” chapter of the QNX Neutrino Programmer's Guide.
    Note: You can have only one timer at a time associated with a thread. You can't currently create a timer for a process CPU-time clock.

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.

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

Library:

libc

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

Description:

The TimerCreate() and TimerCreate_r() kernel calls create a per-process timer using the clock specified by id as the timing base.

These 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 timer_create().
  • At most 50 timer events are generated per clock tick, to limit the consumption of system resources. If the system has a large number of timers set to expire in the same clock period, then at most 50 of the timer events will actually trigger on time; the rest will be handled on the next clock tick (subject to the same limitation of at most 50 timer events).

In order to create a timer that sends a pulse to a process belonging to a different user, your process must have the PROCMGR_AID_CONNECTION ability enabled. For more information about abilities, see procmgr_ability().

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 the event argument is NULL, a SIGALRM signal is sent to your process when the timer expires. To specify a handler for this signal, call sigaction().

Blocking states

These calls don't block.

Returns:

The timer ID of the newly created timer. If an error occurs:

Errors:

EAGAIN
One of the following occurred:
  • All kernel timer objects are in use.
  • (QNX Neutrino 7.0.1 or later) There's already a timer associated with the given thread CPU-time clock.
EFAULT
A fault occurred when the kernel tried to access the buffers provided.
EINVAL
One of the following occurred:
  • The clock ID isn't valid.
  • (QNX Neutrino 7.0.1 or later) You tried to create a timer for a process CPU-time clock.
EPERM
The calling process doesn't have the required permission; see procmgr_ability().

Classification:

QNX Neutrino

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