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:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |
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.