alarm()

Schedule an alarm

Synopsis:

#include <unistd.h>

unsigned int alarm( unsigned int seconds );

Arguments:

seconds

The number of seconds of realtime to let elapse before raising the alarm, or zero to cancel any previous alarm() requests.

Library:

libc

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

Description:

The alarm() function causes the system to send the calling process a SIGALRM signal after a specified number of realtime seconds have elapsed. To add a handler for the signal, call signal() or SignalAction().

---

Because of the nature of time measurement, the signal might actually get sent later than the specified time. For more information, see the Tick, Tock: Understanding the Neutrino Microkernel's Concept of Time chapter of the QNX Neutrino Programmer's Guide. Processor scheduling delays may cause the process to handle the signal after the desired time.

---

The alarm() requests aren't stacked; you can schedule only a single SIGALRM generation in this manner. If the SIGALRM hasn't yet been generated, alarm() reschedules the time at which the SIGALRM is generated.

Returns:

The number of seconds before the calling process is scheduled to receive a SIGALRM from the system, or zero if there was no previous alarm() request.

If an error occurs, an (unsigned)-1 is returned (errno is set).

Errors:

EAGAIN

All timers are in use. You'll have to wait for a process to release one.

Examples:

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

int main()
  {
    unsigned int  timeleft;

    printf( "Set the alarm and sleep\n" );
    alarm( 10 );
    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 = alarm( 0 );
    printf( "Time left before cancel, and rearm: %d\n",
        timeleft );

    /*
     * Start a new timer that kicks us when timeleft
     * seconds have passed.
     */

    alarm( timeleft );

    /*
     * 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 die\n" );
    pause();
    return EXIT_SUCCESS;
  }

Classification:

POSIX 1003.1

Caveats:

Requests from alarm(), TimerAlarm(), and ualarm() 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.

See also:

errno, pause(), signal(), SignalAction(), sleep(), TimerAlarm(), timer_create(), timer_delete(), timer_gettime(), timer_settime(), ualarm()

Tick, Tock: Understanding the Neutrino Microkernel's Concept of Time chapter of the QNX Neutrino Programmer's Guide