Chapter 21. Signals: Signal Handlers

This chapter continues the description of signals begun in the previous chapter. It focuses on signal handlers, and extends the discussion started in Section 20.4. Among the topics we consider are the following:

Designing Signal Handlers

In general, it is preferable to write simple signal handlers. One important reason for this is to reduce the risk of creating race conditions. Two common designs for signal handlers are the following:

In the following sections, we explore these ideas, as well as other concepts that are important in the design of signal handlers.

In The Signal Mask (Blocking Signal Delivery), we noted that delivery of a signal is blocked during the execution of its handler (unless we specify the SA_NODEFER flag to sigaction()). If the signal is (again) generated while the handler is executing, then it is marked as pending and later delivered when the handler returns. We also already noted that signals are not queued. If the signal is generated more than once while the handler is executing, then it is still marked as pending, and it will later be delivered only once.

That signals can “disappear” in this way has implications for how we design signal handlers. To begin with, we can’t reliably count the number of times a signal is generated. Furthermore, we may need to code our signal handlers to deal with the possibility that multiple events of the type corresponding to the signal have occurred. We’ll see an example of this when we consider the use of the SIGCHLD signal in Establishing a Handler for SIGCHLD.

Not all system calls and library functions can be safely called from a signal handler. To understand why requires an explanation of two concepts: reentrant functions and async-signal-safe functions.

To explain what a reentrant function is, we need to first distinguish between single-threaded and multithreaded programs. Classical UNIX programs have a single thread of execution: the CPU processes instructions for a single logical flow of execution through the program. In a multithreaded program, there are multiple, independent, concurrent logical flows of execution within the same process.

In Chapter 29, we’ll see how to explicitly create programs that contain multiple threads of execution. However, the concept of multiple threads of execution is also relevant for programs that employ signal handlers. Because a signal handler may asynchronously interrupt the execution of a program at any point in time, the main program and the signal handler in effect form two independent (although not concurrent) threads of execution within the same process.

A function is said to be reentrant if it can safely be simultaneously executed by multiple threads of execution in the same process. In this context, “safe” means that the function achieves its expected result, regardless of the state of execution of any other thread of execution.

Note

The SUSv3 definition of a reentrant function is one “whose effect, when called by two or more threads, is guaranteed to be as if the threads each executed the function one after the other in an undefined order, even if the actual execution is interleaved.”

A function may be nonreentrant if it updates global or static data structures. (A function that employs only local variables is guaranteed to be reentrant.) If two invocations of (i.e., two threads executing) the function simultaneously attempt to update the same global variable or data structure, then these updates are likely to interfere with each other and produce incorrect results. For example, suppose that one thread of execution is in the middle of updating a linked list data structure to add a new list item when another thread also attempts to update the same linked list. Since adding a new item to the list requires updating multiple pointers, if another thread interrupts these steps and updates the same pointers, chaos will result.

Such possibilities are in fact rife within the standard C library. For example, we already noted in Implementation of malloc() and free() that malloc() and free() maintain a linked list of freed memory blocks available for reallocation from the heap. If a call to malloc() in the main program is interrupted by a signal handler that also calls malloc(), then this linked list can be corrupted. For this reason, the malloc() family of functions, and other library functions that use them, are nonreentrant.

Other library functions are nonreentrant because they return information using statically allocated memory. Examples of such functions (described elsewhere in this book) include crypt(), getpwnam(), gethostbyname(), and getservbyname(). If a signal handler also uses one of these functions, then it will overwrite information returned by any earlier call to the same function from within the main program (or vice versa).

Functions can also be nonreentrant if they use static data structures for their internal bookkeeping. The most obvious examples of such functions are the members of the stdio library (printf(), scanf(), and so on), which update internal data structures for buffered I/O. Thus, when using printf() from within a signal handler, we may sometimes see strange output—or even a program crash or data corruption—if the handler interrupts the main program in the middle of executing a call to printf() or another stdio function.

Even if we are not using nonreentrant library functions, reentrancy issues can still be relevant. If a signal handler updates programmer-defined global data structures that are also updated within the main program, then we can say that the signal handler is nonreentrant with respect to the main program.

If a function is nonreentrant, then its manual page will normally provide an explicit or implicit indication of this fact. In particular, watch out for statements that the function uses or returns information in statically allocated variables.

Example 21-1 demonstrates the nonreentrant nature of the crypt() function (Password Encryption and User Authentication). As command-line arguments, this program accepts two strings. The program performs the following steps:

  1. Call crypt() to encrypt the string in the first command-line argument, and copy this string to a separate buffer using strdup().

  2. Establish a handler for SIGINT (generated by typing Control-C). The handler calls crypt() to encrypt the string supplied in the second command-line argument.

  3. Enter an infinite for loop that uses crypt() to encrypt the string in the first command-line argument and check that the returned string is the same as that saved in step 1.

In the absence of a signal, the strings will always match in step 3. However, if a SIGINT signal arrives and the execution of the signal handler interrupts the main program just after the execution of the crypt() call in the for loop, but before the check to see if the strings match, then the main program will report a mismatch. When we run the program, this is what we see:

$ ./non_reentrant abc def
Repeatedly type Control-C to generate SIGINT
Mismatch on call 109871 (mismatch=1 handled=1)
Mismatch on call 128061 (mismatch=2 handled=2)
Many lines of output removed
Mismatch on call 727935 (mismatch=149 handled=156)
Mismatch on call 729547 (mismatch=150 handled=157)
Type Control-\ to generate SIGQUIT
Quit (core dumped)

Comparing the mismatch and handled values in the above output, we see that in the majority of cases where the signal handler is invoked, it overwrites the statically allocated buffer between the call to crypt() and the string comparison in main().

Example 21-1. Calling a nonreentrant function from both main() and a signal handler

signals/nonreentrant.c
#define _XOPEN_SOURCE 600
#include <unistd.h>
#include <signal.h>
#include <string.h>
#include "tlpi_hdr.h"

static char *str2;              /* Set from argv[2] */
static int handled = 0;         /* Counts number of calls to handler */

static void
handler(int sig)
{

    crypt(str2, "xx");
    handled++;
}
int
main(int argc, char *argv[])
{
    char *cr1;
    int callNum, mismatch;
    struct sigaction sa;

    if (argc != 3)
        usageErr("%s str1 str2\n", argv[0]);

    str2 = argv[2];                      /* Make argv[2] available to handler */
    cr1 = strdup(crypt(argv[1], "xx"));  /* Copy statically allocated string
                                            to another buffer */
    if (cr1 == NULL)
        errExit("strdup");

    sigemptyset(&sa.sa_mask);
    sa.sa_flags = 0;
    sa.sa_handler = handler;
    if (sigaction(SIGINT, &sa, NULL) == -1)
        errExit("sigaction");

    /* Repeatedly call crypt() using argv[1]. If interrupted by a
       signal handler, then the static storage returned by crypt()
       will be overwritten by the results of encrypting argv[2], and
       strcmp() will detect a mismatch with the value in 'cr1'. */

    for (callNum = 1, mismatch = 0; ; callNum++) {
        if (strcmp(crypt(argv[1], "xx"), cr1) != 0) {
            mismatch++;
            printf("Mismatch on call %d (mismatch=%d handled=%d)\n",
                    callNum, mismatch, handled);
        }
    }
}
     signals/nonreentrant.c

An async-signal-safe function is one that the implementation guarantees to be safe when called from a signal handler. A function is async-signal-safe either because it is reentrant or because it is not interruptible by a signal handler.

Table 21-1 lists the functions that various standards require to be async-signal-safe. In this table, the functions whose names are not followed by a v2 or v3 were specified as async-signal-safe in POSIX.1-1990. SUSv2 added the functions marked v2 to the list, and those marked v3 were added by SUSv3. Individual UNIX implementations may make other functions async-signal-safe, but all standards-conformant UNIX implementations must ensure that at least these functions are async-signal-safe (if they are provided by the implementation; not all of these functions are provided on Linux).

SUSv4 makes the following changes to Table 21-1:

Table 21-1. Functions required to be async-signal-safe by POSIX.1-1990, SUSv2, and SUSv3

_Exit()(v3)

_exit()

abort() (v3)

accept() (v3)

access()

aio_error() (v2)

aio_return()(v2)

aio_suspend() (v2)

alarm()

bind()(v3)

cfgetispeed()

cfgetospeed()

cfsetispeed()

cfsetospeed()

chdir()

chmod()

chown()

clock_gettime() (v2)

close()

connect() (v3)

creat()

dup()

dup2()

execle()

execve()

fchmod() (v3)

fchown() (v3)

fcntl()

fdatasync() (v2)

fork()

fpathconf() (v2)

fstat()

fsync() (v2)

ftruncate() (v3)

getegid()

geteuid()

getgid()

getgroups()

getpeername() (v3)

getpgrp()

getpid()

getppid()

getsockname() (v3)

getsockopt() (v3)

getuid()

kill()

link()

listen() (v3)

lseek()

lstat() (v3)

mkdir()

mkfifo()

open()

pathconf()

pause()

pipe()

poll() (v3)

posix_trace_event() (v3)

pselect() (v3)

raise() (v2)

read()

readlink() (v3)

recv() (v3)

recvfrom() (v3)

recvmsg() (v3)

rename()

rmdir()

select() (v3)

sem_post() (v2)

send() (v3)

sendmsg() (v3)

sendto() (v3)

setgid()

setpgid()

setsid()

setsockopt() (v3)

setuid()

shutdown() (v3)

sigaction()

sigaddset()

sigdelset()

sigemptyset()

sigfillset()

sigismember()

signal() (v2)

sigpause() (v2)

sigpending()

sigprocmask()

sigqueue() (v2)

sigset() (v2)

sigsuspend()

sleep()

socket() (v3)

sockatmark() (v3)

socketpair() (v3)

stat()

symlink() (v3)

sysconf()

tcdrain()

tcflow()

tcflush()

tcgetattr()

tcgetpgrp()

tcsendbreak()

tcsetattr()

tcsetpgrp()

time()

timer_getoverrun() (v2)

timer_gettime() (v2)

timer_settime() (v2)

times()

umask()

uname()

unlink()

utime()

wait()

waitpid()

write()

SUSv3 notes that all functions not listed in Table 21-1 are considered to be unsafe with respect to signals, but points out that a function is unsafe only when invocation of a signal handler interrupts the execution of an unsafe function, and the handler itself also calls an unsafe function. In other words, when writing signal handlers, we have two choices:

  • Ensure that the code of the signal handler itself is reentrant and that it calls only async-signal-safe functions.

  • Block delivery of signals while executing code in the main program that calls unsafe functions or works with global data structures also updated by the signal handler.

The problem with the second approach is that, in a complex program, it can be difficult to ensure that a signal handler will never interrupt the main program while it is calling an unsafe function. For this reason, the above rules are often simplified to the statement that we must not call unsafe functions from within a signal handler.

Note

If we set up the same handler function to deal with several different signals or use the SA_NODEFER flag to sigaction(), then a handler may interrupt itself. As a consequence, the handler may be nonreentrant if it updates global (or static) variables, even if they are not used by the main program.

Because they may update errno, use of the functions listed in Table 21-1 can nevertheless render a signal handler nonreentrant, since they may overwrite the errno value that was set by a function called from the main program. The workaround is to save the value of errno on entry to a signal handler that uses any of the functions in Table 21-1 and restore the errno value on exit from the handler, as in the following example:

void
handler(int sig)
{
    int savedErrno;

    savedErrno = errno;

    /* Now we can execute a function that might modify errno */

    errno = savedErrno;
}

Although printf() is not async-signal-safe, we use it in signal handlers in various example programs in this book. We do so because printf() provides an easy and concise way to demonstrate that a signal handler has been called, and to display the contents of relevant variables within the handler. For similar reasons, we occasionally use a few other unsafe functions in signal handlers, including other stdio functions and strsignal().

Real-world applications should avoid calling non-async-signal-safe functions from signal handlers. To make this clear, each signal handler in the example programs that uses one of these functions is marked with a comment indicating that the usage is unsafe:

printf("Some message\n");           /* UNSAFE */

Notwithstanding reentrancy issues, it can be useful to share global variables between the main program and a signal handler. This can be safe as long as the main program correctly handles the possibility that the signal handler may change the global variable at any time. For example, one common design is to make a signal handler’s sole action the setting of a global flag. This flag is periodically checked by the main program, which then takes appropriate action in response to the delivery of the signal (and clears the flag). When global variables are accessed in this way from a signal handler, we should always declare them using the volatile attribute (see Performing a Nonlocal Goto: setjmp() and long jmp()) in order to prevent the compiler from performing optimizations that result in the variable being stored in a register.

Reading and writing global variables may involve more than one machine-language instruction, and a signal handler may interrupt the main program in the middle of such an instruction sequence. (We say that access to the variable is nonatomic.) For this reason, the C language standards and SUSv3 specify an integer data type, sig_atomic_t, for which reads and writes are guaranteed to be atomic. Thus, a global flag variable that is shared between the main program and a signal handler should be declared as follows:

volatile sig_atomic_t flag;

We show an example of the use of the sig_atomic_t data type in Example 22-5, in Example program.

Note that the C increment (++) and decrement (--) operators don’t fall within the guarantee provided for sig_atomic_t. On some hardware architectures, these operations may not be atomic (refer to Protecting Accesses to Shared Variables: Mutexes for more details). All that we are guaranteed to be safely allowed to do with a sig_atomic_t variable is set it within the signal handler, and check it in the main program (or vice versa).

C99 and SUSv3 specify that an implementation should define two constants (in <stdint.h>), SIG_ATOMIC_MIN and SIG_ATOMIC_MAX, that define the range of values that may be assigned to variables of type sig_atomic_t. The standards require that this range be at least -127 to 127 if sig_atomic_t is represented as a signed value, or 0 to 255 if it is represented as an unsigned value. On Linux, these two constants equate to the negative and positive limits for signed 32-bit integers.