ualarm()

Schedule an alarm

Synopsis:

#include <unistd.h>

useconds_t ualarm( useconds_t usec,
                   useconds_t interval );

Arguments:

usec: The number of microseconds that you want to elapse before the first alarm occurs, or 0 to cancel any previous request for an alarm.
interval: Zero, or the number of microseconds that you want to elapse before the subsequent alarms occur.

Library:

libc

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

Description:

The ualarm() function causes the system to send the calling process a SIGALRM signal after usec microseconds of real time have elapsed. If the interval argument is nonzero, the alarm is then sent every interval microseconds after that.

Processor scheduling delays may cause a delay between when the signal is sent and when the process actually handles it.

If usec is 0, any previous ualarm() request is cancelled.

Note: 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.

Returns:

0: There was no previous ualarm() request.
-1: An error occurred (errno is set).
Any other value: The number of microseconds until the next scheduled SIGALRM.

Errors:

EAGAIN: All timers are in use; wait for a process to release one and try again.

Examples:

#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>

int main( void )
{
    useconds_t timeleft;

    printf( "Set the alarm and sleep\n" );
    ualarm( (useconds_t)( 10 * 1000 * 1000 ), 0 );
    sleep( 5 );   /* go to sleep for 5 seconds */

    /*
     To get the time left before the SIGALRM is 
     to arrive, one must cancel the initial timer, 
     which returns the amount of time it had 
     remaining.
    */
    timeleft = ualarm( 0, 0 );
    printf( "Time left before cancel, and rearm: %ld\n",
        timeleft );

    /*
     Start a new timer that kicks us when timeleft
     seconds have passed.
    */
    ualarm( timeleft, 0 );

    /*
     Wait until we receive the SIGALRM signal; any
     signal kills us, though, since we don't have
     a signal handler.
    */
    printf( "Hanging around, waiting to exit\n" );
    pause();
    
    /* You'll never get here. */
    return EXIT_SUCCESS;
}

Classification:

Standard Unix; removed from POSIX.1-2008

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

Caveats:

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

Don't mix calls to ualarm() with nanosleep(), sleep(), timer_create(), timer_delete(), timer_getoverrun(), timer_gettime(), timer_settime(), or usleep().