timer_create()

create a timer

Synopsis:

#include <signal.h>
#include <time.h>
timer_t timer_create( clockid_t clock_id,
                      struct sigevent *evp );

Description:

The timer_create() function creates a per-process timer using the specified clock source, clock_id, as the timing base. The only supported clock ID is CLOCK_REALTIME.

The returned timer ID is used in subsequent calls to timer_gettime(), timer_settime() and timer_delete().

The timer is created in the disabled state, and isn't enabled until timer_settime() is called.

The sigevent structure pointed to by evp contains at least the following member:

int sigev_signo

If sigev_signo is positive, it's interpreted as a signal number to be sent to the calling process when the timer expires.

If sigev_signo is negative then it's interpreted as a proxy to trigger when the timer expires. If evp is NULL, then a signal of SIGALRM is set when the timer expires.

If sigev_signo is 0, the process sleeps until the timer expires.

If you need a timer that fires off every 50 milliseconds and you wish to execute some code on each pulse, the qnx_hint_attach() function is a more efficient, but less portable, alternative.

Returns:

A timer ID (a small positive integer) on success. On error, -1 is returned and errno is set.

Errors:

EAGAIN: All timers are in use. You'll have to wait for a process to release one.
EINVAL: The clock_id isn't CLOCK_REALTIME.

Examples:

#include <stdio.h>
#include <signal.h>
#include <time.h>
#include <sys/proxy.h>
#include <sys/kernel.h>

int main( void )
  {
    pid_t proxy;
    timer_t id, i;
    struct itimerspec timer;
    struct sigevent event;

    /* Get a proxy for the timer to kick */
    proxy = qnx_proxy_attach( 0, 0, 0, -1 );
    if( proxy == -1 ) {
      printf( "Unable to attach proxy." );
      return;
    }

    /* Attach to the timer */
    event.sigev_signo = -proxy;
    id = timer_create( CLOCK_REALTIME, &event );
    if( id == -1 ) {
      printf( "Unable to attach timer." );
      return;
    }

    /*
     * 4 seconds before initial firing ,
     * 1 second repetitive timer afterwards.
     */
    timer.it_value.tv_sec     = 4L;
    timer.it_value.tv_nsec    = 0L;
    timer.it_interval.tv_sec  = 1L;
    timer.it_interval.tv_nsec = 0L;
    timer_settime( id, 0, &timer, NULL );

    /* Wait for the proxy */
    for( i = 0 ; i < 10 ; ++i ) {
      Receive( proxy, 0, 0 );
      printf( "Tick.\n" );
    }

    /* Set an absolute timer to go off in 20 sec */
    timer.it_value.tv_sec     = time( NULL ) + 20;
    timer.it_value.tv_nsec    = 0L;
    timer.it_interval.tv_sec  = 0L;
    timer.it_interval.tv_nsec = 0L;
    timer_settime( id, TIMER_ABSTIME, &timer, NULL );

    /* Clear pending proxies */
    while( Creceive( proxy, 0, 0 ) == proxy )
      ;

    /*
     * Count down as we wait for next proxy
     * ( about 20 seconds )
     */
    while( Creceive( proxy, 0, 0 ) != proxy ) {
      timer_gettime( id, &timer );
      printf( "Remaining %2ld\r", timer.it_value.tv_sec );
    }
    printf( "\n" );

    timer_delete( id );
    return( EXIT_SUCCESS );
  }

Classification:

QNX

Safety:
Interrupt handler	No
Signal handler	Yes
Thread	Yes

Caveats:

This function is based on a draft of POSIX, and doesn't use the prototype specified in POSIX 1003.4. Programs using this function won't be portable.