Section 10.10. alarm and pause Functions

10.10. alarm and pause Functions

The alarm function allows us to set a timer that will expire at a specified time in the future. When the timer expires, the SIGALRM signal is generated. If we ignore or don't catch this signal, its default action is to terminate the process.

 #include <unistd.h> unsigned int alarm(unsigned int seconds); 

Returns: 0 or number of seconds until previously set alarm

The seconds value is the number of clock seconds in the future when the signal should be generated. Be aware that when that time occurs, the signal is generated by the kernel, but there could be additional time before the process gets control to handle the signal, because of processor scheduling delays.

Earlier UNIX System implementations warned that the signal could also be sent up to 1 second early. POSIX.1 does not allow this.

There is only one of these alarm clocks per process. If, when we call alarm, a previously registered alarm clock for the process has not yet expired, the number of seconds left for that alarm clock is returned as the value of this function. That previously registered alarm clock is replaced by the new value.

If a previously registered alarm clock for the process has not yet expired and if the seconds value is 0, the previous alarm clock is canceled. The number of seconds left for that previous alarm clock is still returned as the value of the function.

Although the default action for SIGALRM is to terminate the process, most processes that use an alarm clock catch this signal. If the process then wants to terminate, it can perform whatever cleanup is required before terminating. If we intend to catch SIGALRM, we need to be careful to install its signal handler before calling alarm. If we call alarm first and are sent SIGALRM before we can install the signal handler, our process will terminate.

The pause function suspends the calling process until a signal is caught.

 #include <unistd.h> int pause(void); 

Returns: 1 with errno set to EINTR

The only time pause returns is if a signal handler is executed and that handler returns. In that case, pause returns 1 with errno set to EINTR.

Example

Using alarm and pause, we can put a process to sleep for a specified amount of time. The sleep1 function in Figure 10.7 appears to do this (but it has problems, as we shall see shortly).

This function looks like the sleep function, which we describe in Section 10.19, but this simple implementation has three problems.

1. If the caller already has an alarm set, that alarm is erased by the first call to alarm. We can correct this by looking at the return value from the first call to alarm. If the number of seconds until some previously set alarm is less than the argument, then we should wait only until the previously set alarm expires. If the previously set alarm will go off after ours, then before returning we should reset this alarm to occur at its designated time in the future.

2. We have modified the disposition for SIGALRM. If we're writing a function for others to call, we should save the disposition when we're called and restore it when we're done. We can correct this by saving the return value from signal and resetting the disposition before we return.

3. There is a race condition between the first call to alarm and the call to pause. On a busy system, it's possible for the alarm to go off and the signal handler to be called before we call pause. If that happens, the caller is suspended forever in the call to pause (assuming that some other signal isn't caught).

Earlier implementations of sleep looked like our program, with problems 1 and 2 corrected as described. There are two ways to correct problem 3. The first uses setjmp, which we show in the next example. The other uses sigprocmask and sigsuspend, and we describe it in Section 10.19.

Figure 10.7. Simple, incomplete implementation of sleep

 #include     <signal.h> #include     <unistd.h> static void sig_alrm(int signo) {     /* nothing to do, just return to wake up the pause */ } unsigned int sleep1(unsigned int nsecs) {     if (signal(SIGALRM, sig_alrm) == SIG_ERR)         return(nsecs);     alarm(nsecs);       /* start the timer */     pause();            /* next caught signal wakes us up */     return(alarm(0));   /* turn off timer, return unslept time */ } 

Example

The SVR2 implementation of sleep used setjmp and longjmp (Section 7.10) to avoid the race condition described in problem 3 of the previous example. A simple version of this function, called sleep2, is shown in Figure 10.8. (To reduce the size of this example, we don't handle problems 1 and 2 described earlier.)

The sleep2 function avoids the race condition from Figure 10.7. Even if the pause is never executed, the sleep2 function returns when the SIGALRM occurs.

There is, however, another subtle problem with the sleep2 function that involves its interaction with other signals. If the SIGALRM interrupts some other signal handler, when we call longjmp, we abort the other signal handler. Figure 10.9 shows this scenario. The loop in the SIGINT handler was written so that it executes for longer than 5 seconds on one of the systems used by the author. We simply want it to execute longer than the argument to sleep2. The integer k is declared volatile to prevent an optimizing compiler from discarding the loop. Executing the program shown in Figure 10.9 gives us

     $ ./a.out      ^?                      we type the interrupt character     sig_int starting     sleep2 returned: 0 

We can see that the longjmp from the sleep2 function aborted the other signal handler, sig_int, even though it wasn't finished. This is what you'll encounter if you mix the SVR2 sleep function with other signal handling. See Exercise 10.3.

Figure 10.8. Another (imperfect) implementation of sleep

 #include   <setjmp.h> #include   <signal.h> #include   <unistd.h> static jmp_buf  env_alrm; static void sig_alrm(int signo) {     longjmp(env_alrm, 1); } unsigned int sleep2(unsigned int nsecs) {     if (signal(SIGALRM, sig_alrm) == SIG_ERR)         return(nsecs);     if (setjmp(env_alrm) == 0) {         alarm(nsecs);       /* start the timer */         pause();            /* next caught signal wakes us up */     }     return(alarm(0));       /* turn off timer, return unslept time */ } 

Figure 10.9. Calling sleep2 from a program that catches other signals

 #include "apue.h" unsigned int        sleep2(unsigned int); static void         sig_int(int); int main(void) {     unsigned int        unslept;     if (signal(SIGINT, sig_int) == SIG_ERR)         err_sys("signal(SIGINT) error");     unslept = sleep2(5);     printf("sleep2 returned: %u\n", unslept);     exit(0); } static void sig_int(int signo) {     int            i, j;     volatile int   k;     /*      * Tune these loops to run for more than 5 seconds      * on whatever system this test program is run.      */     printf("\nsig_int starting\n");     for (i = 0; i < 300000; i++)         for (j = 0; j < 4000; j++)             k += i * j;     printf("sig_int finished\n"); } 

The purpose of these two examples, the sleep1 and sleep2 functions, is to show the pitfalls in dealing naively with signals. The following sections will show ways around all these problems, so we can handle signals reliably, without interfering with other pieces of code.

Example

A common use for alarm, in addition to implementing the sleep function, is to put an upper time limit on operations that can block. For example, if we have a read operation on a device that can block (a "slow" device, as described in Section 10.5), we might want the read to time out after some amount of time. The program in Figure 10.10 does this, reading one line from standard input and writing it to standard output.

This sequence of code is common in UNIX applications, but this program has two problems.

1. The program in Figure 10.10 has one of the same flaws that we described in Figure 10.7: a race condition between the first call to alarm and the call to read. If the kernel blocks the process between these two function calls for longer than the alarm period, the read could block forever. Most operations of this type use a long alarm period, such as a minute or more, making this unlikely; nevertheless, it is a race condition.

2. If system calls are automatically restarted, the read is not interrupted when the SIGALRM signal handler returns. In this case, the timeout does nothing.

Here, we specifically want a slow system call to be interrupted. POSIX.1 does not give us a portable way to do this; however, the XSI extension in the Single UNIX Specification does. We'll discuss this more in Section 10.14.

Figure 10.10. Calling read with a timeout

 #include "apue.h" static void sig_alrm(int); int main(void) {     int     n;     char    line[MAXLINE];     if (signal(SIGALRM, sig_alrm) == SIG_ERR)         err_sys("signal(SIGALRM) error");     alarm(10);     if ((n = read(STDIN_FILENO, line, MAXLINE)) < 0)         err_sys("read error");     alarm(0);     write(STDOUT_FILENO, line, n);     exit(0); } static void sig_alrm(int signo) {     /* nothing to do, just return to interrupt the read */ } 

Example

Let's redo the preceding example using longjmp. This way, we don't need to worry about whether a slow system call is interrupted.

This version works as expected, regardless of whether the system restarts interrupted system calls. Realize, however, that we still have the problem of interactions with other signal handlers, as in Figure 10.8.

Figure 10.11. Calling read with a timeout, using longjmp

 #include "apue.h" #include <setjmp.h> static void       sig_alrm(int); static jmp_buf    env_alrm; int main(void) {     int     n;     char    line[MAXLINE];     if (signal(SIGALRM, sig_alrm) == SIG_ERR)         err_sys("signal(SIGALRM) error");     if (setjmp(env_alrm) != 0)         err_quit("read timeout");     alarm(10);     if ((n = read(STDIN_FILENO, line, MAXLINE)) < 0)         err_sys("read error");     alarm(0);     write(STDOUT_FILENO, line, n);     exit(0); } static void sig_alrm(int signo) {     longjmp(env_alrm, 1); } 

If we want to set a time limit on an I/O operation, we need to use longjmp, as shown previously, realizing its possible interaction with other signal handlers. Another option is to use the select or poll functions, described in Sections 14.5.1 and 14.5.2.