Section 10.15. sigsetjmp and siglongjmp Functions

10.15. sigsetjmp and siglongjmp Functions

In Section 7.10, we described the setjmp and longjmp functions, which can be used for nonlocal branching. The longjmp function is often called from a signal handler to return to the main loop of a program, instead of returning from the handler. We saw this in Figures 10.8 and 10.11.

There is a problem in calling longjmp, however. When a signal is caught, the signal-catching function is entered with the current signal automatically being added to the signal mask of the process. This prevents subsequent occurrences of that signal from interrupting the signal handler. If we longjmp out of the signal handler, what happens to the signal mask for the process?

Under FreeBSD 5.2.1 and Mac OS X 10.3, setjmp and longjmp save and restore the signal mask. Linux 2.4.22 and Solaris 9, however, do not do this. FreeBSD and Mac OS X provide the functions _setjmp and _longjmp, which do not save and restore the signal mask.

To allow either form of behavior, POSIX.1 does not specify the effect of setjmp and longjmp on signal masks. Instead, two new functions, sigsetjmp and siglongjmp, are defined by POSIX.1. These two functions should always be used when branching from a signal handler.

 #include <setjmp.h> int sigsetjmp(sigjmp_buf env, int savemask); 

Returns: 0 if called directly, nonzero if returning from a call to siglongjmp

void siglongjmp(sigjmp_buf env, int val);

The only difference between these functions and the setjmp and longjmp functions is that sigsetjmp has an additional argument. If savemask is nonzero, then sigsetjmp also saves the current signal mask of the process in env. When siglongjmp is called, if the env argument was saved by a call to sigsetjmp with a nonzero savemask, then siglongjmp restores the saved signal mask.

Example

The program in Figure 10.20 demonstrates how the signal mask that is installed by the system when a signal handler is invoked automatically includes the signal being caught. The program also illustrates the use of the sigsetjmp and siglongjmp functions.

This program demonstrates another technique that should be used whenever siglongjmp is called from a signal handler. We set the variable canjump to a nonzero value only after we've called sigsetjmp. This variable is also examined in the signal handler, and siglongjmp is called only if the flag canjump is nonzero. This provides protection against the signal handler being called at some earlier or later time, when the jump buffer isn't initialized by sigsetjmp. (In this trivial program, we terminate quickly after the siglongjmp, but in larger programs, the signal handler may remain installed long after the siglongjmp.) Providing this type of protection usually isn't required with longjmp in normal C code (as opposed to a signal handler). Since a signal can occur at any time, however, we need the added protection in a signal handler.

Here, we use the data type sig_atomic_t, which is defined by the ISO C standard to be the type of variable that can be written without being interrupted. By this we mean that a variable of this type should not extend across page boundaries on a system with virtual memory and can be accessed with a single machine instruction, for example. We always include the ISO type qualifier volatile for these data types too, since the variable is being accessed by two different threads of control: the main function and the asynchronously executing signal handler. Figure 10.21 shows a time line for this program.

We can divide Figure 10.21 into three parts: the left part (corresponding to main), the center part (sig_usr1), and the right part (sig_alrm). While the process is executing in the left part, its signal mask is 0 (no signals are blocked). While executing in the center part, its signal mask is SIGUSR1. While executing in the right part, its signal mask is SIGUSR1|SIGALRM.

Let's examine the output when the program in Figure 10.20 is executed:

    $ ./a.out &                      start process in background    starting main:    [1]   531                        the job-control shell prints its process ID    $ kill -USR1 531                 send the process SIGUSR1    starting sig_usr1: SIGUSR1    $ in sig_alrm: SIGUSR1 SIGALRM    finishing sig_usr1: SIGUSR1    ending main:                                     just press RETURN    [1] + Done          ./a.out & 

The output is as we expect: when a signal handler is invoked, the signal being caught is added to the current signal mask of the process. The original mask is restored when the signal handler returns. Also, siglongjmp restores the signal mask that was saved by sigsetjmp.

If we change the program in Figure 10.20 so that the calls to sigsetjmp and siglongjmp are replaced with calls to setjmp and longjmp on Linux (or _setjmp and _longjmp on FreeBSD), the final line of output becomes

     ending main: SIGUSR1

This means that the main function is executing with the SIGUSR1 signal blocked, after the call to setjmp. This probably isn't what we want.

Figure 10.20. Example of signal masks, sigsetjmp, and siglongjmp

 #include "apue.h" #include <setjmp.h> #include <time.h> static void                         sig_usr1(int), sig_alrm(int); static sigjmp_buf                   jmpbuf; static volatile sig_atomic_t        canjump; int main(void) {     if (signal(SIGUSR1, sig_usr1) == SIG_ERR)         err_sys("signal(SIGUSR1) error");     if (signal(SIGALRM, sig_alrm) == SIG_ERR)         err_sys("signal(SIGALRM) error");     pr_mask("starting main: ");     /* Figure 10.14 */     if (sigsetjmp(jmpbuf, 1)) {         pr_mask("ending main: ");         exit(0);     }     canjump = 1;         /* now sigsetjmp() is OK */     for ( ; ; )         pause(); } static void sig_usr1(int signo) {     time_t  starttime;     if (canjump == 0)         return;     /* unexpected signal, ignore */     pr_mask("starting sig_usr1: ");     alarm(3);               /* SIGALRM in 3 seconds */     starttime = time(NULL);     for ( ; ; )             /* busy wait for 5 seconds */         if (time(NULL) > starttime + 5)             break;     pr_mask("finishing sig_usr1: ");     canjump = 0;     siglongjmp(jmpbuf, 1);  /* jump back to main, don't return */ } static void sig_alrm(int signo) {     pr_mask("in sig_alrm: "); } 

Figure 10.21. Time line for example program handling two signals