alarm()--Set Schedule for Alarm Signal

 #include <unistd.h>

 unsigned int alarm( unsigned int seconds );   

The alarm() function generates a SIGALRM signal after the number of seconds specified by the seconds parameter have elapsed. The delivery of the SIGALRM signal is directed at the calling process.

seconds is the number of real seconds to elapse before the SIGALRM is generated. Because of processor delays, the SIGALRM may be generated slightly later than this specified time. If seconds is zero, any previously set alarm request is canceled.

Only one such alarm can be active at a time for the process. If a new alarm time is set, any previous alarm is canceled.

Authorities and Locks

None.

Parameters

seconds

(Input) The number of real seconds to elapse before generating the signal.

Return Value

Error Conditions

If alarm() is not successful, errno usually indicates the following error. Under some conditions, errno could indicate an error other than that listed here.

[ENOTSIGINIT]

Process not enabled for signals.

An attempt was made to call a signal function under one of the following conditions:

• The signal function is being called for a process that is not enabled for asynchronous signals.
• The signal function is being called when the system signal controls have not been initialized.

Usage Notes

The alarm() function enables a process for signals if the process is not already enabled for signals. For details, see Qp0sEnableSignals()--Enable Process for Signals. If the system has not been enabled for signals, alarm() is not successful, and an [ENOTSIGINIT] error is returned.

Related Information

• The <signal.h> file (see Header Files for UNIX-Type Functions)
  
  
• The <unistd.h> file
  
  
• pause()--Suspend Process Until Signal Received
  
  
• Qp0sDisableSignals()--Disable Process for Signals
  
  
• Qp0sEnableSignals()--Enable Process for Signals
  
  
• setitimer()--Set Value for Interval Timer
  
  
• sigaction()--Examine and Change Signal Action
  
  
• sigsuspend()--Wait for Signal
  
  
• sleep()--Suspend Processing for Interval of Time
  
  
• usleep()--Suspend Processing for Interval of Time

Example

See Code disclaimer information for information pertaining to code examples.

The following example generates a SIGALRM signal using the alarm() function:

#include <signal.h>
#include <unistd.h>
#include <stdio.h>
#include <time.h>
#include <errno.h>

#define LOOP_LIMIT  1E6

volatile int sigcount=0;

void catcher( int sig ) {
    printf( "Signal catcher called for signal %d\n", sig );
    sigcount = 1;
}

int main( int argc, char *argv[] )  {

    struct sigaction sact;
    volatile double count;
    time_t t;

    sigemptyset( &sact.sa_mask );
    sact.sa_flags = 0;
    sact.sa_handler = catcher;
    sigaction( SIGALRM, &sact, NULL );

    alarm(5);  /* timer will pop in five seconds */

    time( &t );
    printf( "Before loop, time is %s", ctime(&t) );

    for( count=0; ((count<LOOP_LIMIT) && (sigcount==0)); count++ );

    time( &t );
    printf( "After loop, time is %s\n", ctime(&t) );

    if( sigcount == 0 )
        printf( "The signal catcher never gained control\n" );
    else
        printf( "The signal catcher gained control\n" );

    printf( "The value of count is %.0f\n", count );

    return( 0 );
}

Output:

    Before loop, time is Sun Jan 22 10:14:00 1995
    Signal catcher called for signal 14
    After loop, time is Sun Jan 22 10:14:05 1995
    The signal catcher gained control
    The value of count is 290032