TimerCreate(), TimerCreate_r()

QNX SDP8.0C Library ReferenceAPIDeveloper

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 clock source that you want to use, 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 — in this release, this is equivalent to CLOCK_REALTIME.
  • CLOCK_MONOTONIC — this clock always increases at a constant rate and can't be adjusted.
  • CLOCK_THREAD_CPUTIME_ID, which refers to the calling thread, 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.
    Note:
    • The accuracy of this timer depends on the clock period. The thread may exceed the requested execution time, and the actual amount of time it uses is at least the timeout you specified but less than the same amount plus the clock period.
    • At any moment, only one timer in the whole system can be using a specific thread's or process's CPU-time clock ID. If there's already a timer for the given CPU-time clock ID, timer_create() gives an error of EAGAIN.
    • For more information, see Monitoring execution times in the Understanding the Microkernel's Concept of Time chapter of the QNX OS Programmer's Guide.
  • CLOCK_PROCESS_CPUTIME_ID, which refers to the calling process, or a process CPU-time clock ID return by clock_getcpuclockid() or ClockId(). The timeout that you set for this type of timer represents the process's execution time. For more information, see the CLOCK_THREAD_CPUTIME_ID entry above.
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. The timer is created in the disabled state, and isn't enabled until you call TimerSettime().

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

You can use the returned timer ID in subsequent calls to the other timer functions.

Note:
  • Instead of using these kernel calls directly, consider calling timer_create().
  • 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, see procmgr_ability().
  • At most 50 timer events are generated per clock tick (or system tick), to limit the consumption of system resources. If the system has a large number of timers set to expire on the same clock tick, 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).

The sigevent structure pointed to by event contains the event to deliver when the timer fires. The event doesn't need to be registered. We recommend the following event types:

  • 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.

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 ID of the newly created timer. If an error occurs:

  • TimerCreate() returns -1 and sets errno.
  • TimerCreate_r() returns the negative of a value from the Errors section and doesn't set errno.

Errors:

EAGAIN
One of the following occurred:
  • All timers are in use; your process must release one.
  • There's already a timer associated with the given 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 is invalid.
  • The event type is SIGEV_INTR.
EPERM
The calling process doesn't have the required permission; see procmgr_ability().

Classification:

QNX OS

Safety:
Cancellation pointNo
Signal handlerYes
ThreadYes
Page updated: