You change a signal’s action with the signal() function. You can change the action to one of “ignore this signal,” “restore the system’s default action for this signal,” or “call my function with the signal number as a parameter when the signal occurs.”

A function you provide to deal with the signal is called a signal handler (or just a handler), and putting a handler in place is arranging to catch the signal.

With that introduction, let’s proceed to the APIs. The <signal.h> header file provides macro definitions for supported signals and declares the signal management function provided by Standard C:

#include <signal.h>                                              ISO C

void (*signal(int signum, void (*func)(int)))(int);

This declaration for signal() is almost impossible to read. Thus, the GNU/Linux signal(2) manpage defines it this way:

typedef void (*sighandler_t)(int);

sighandler_t signal(int signum, sighandler_t handler);

Now it’s more intelligible. The type sighandler_t is a pointer to a function returning void, which accepts a single integer argument. This integer is the number of the arriving signal.

The signal() function accepts a signal number as its first parameter and a pointer to a function (the new handler) as its second argument. If not a function pointer, the second argument may be either SIG_DFL, which means “restore the default action,” or SIG_IGN, which means “ignore the signal.”

signal() changes the action for signum and returns the previous action. (This allows you to later restore the previous action if you so desire.) The return value may also be SIG_ERR, which indicates that something went wrong. (Some signals can’t be caught or ignored; supplying a signal handler for them, or an invalid signum, generates this error return.) Table 10.1 lists the signals available under GNU/Linux, their numeric values, each one’s default action, the formal standard or modern operating system that defines them, and each one’s meaning.

Older versions of the Bourne shell (/bin/sh) associated traps, which are shell-level signal handlers, directly with signal numbers. Thus, the well-rounded Unix programmer needed to know not only the signal names for use from C code but also the corresponding signal numbers! POSIX requires the trap command to understand symbolic signal names (without the ’SIG’ prefix), so this is no longer necessary. However (mostly against our better judgment), we have provided the numbers in the interest of completeness and because you may one day have to deal with a pre-POSIX shell script or ancient C code that uses signal numbers directly.

Some systems also define other signals, such as SIGEMT, SIGLOST, and SIGINFO. The GNU/Linux signal(7) manpage provides a complete listing; if your program needs to handle signals not supported by GNU/Linux, the way to do it is with an #ifdef:

#ifdef SIGLOST
... handle SIGLOST here ...
#endif

With the exception of SIGSTKFLT, the signals listed in Table 10.1 are widely available and don’t need to be bracketed with #ifdef.

SIGKILL and SIGSTOP cannot be caught or ignored (or blocked, as described later in the chapter). They always perform the default action listed in Table 10.1.

You can use ’kill -l’ to see a list of supported signals. From one of our GNU/Linux systems:

$ kill -1
 1) SIGHUP       2) SIGINT       3) SIGQUIT      4) SIGILL
 5) SIGTRAP      6) SIGABRT      7) SIGBUS       8) SIGFPE
 9) SIGKILL     10) SIGUSR1     11) SIGSEGV     12) SIGUSR2
13) SIGPIPE     14) SIGALRM     15) SIGTERM     17) SIGCHLD
18) SIGCONT     19) SIGSTOP     20) SIGTSTP     21) SIGTTIN
22) SIGTTOU     23) SIGURG      24) SIGXCPU     25) SIGXFSZ
26) SIGVTALRM   27) SIGPROF     28) SIGWINCH    29) SIGIO
30) SIGPWR      31) SIGSYS      32) SIGRTMIN    33) SIGRTMIN+1
34) SIGRTMIN+2  35) SIGRTMIN+3  36) SIGRTMIN+4  37) SIGRTMIN+5
38) SIGRTMIN+6  39) SIGRTMIN+7  40) SIGRTMIN+8  41) SIGRTMIN+9
42) SIGRTMIN+10 43) SIGRTMIN+11 44) SIGRTMIN+12 45) SIGRTMIN+13
46) SIGRTMIN+14 47) SIGRTMIN+15 48) SIGRTMAX-15 49) SIGRTMAX-14
50) SIGRTMAX-13 51) SIGRTMAX-12 52) SIGRTMAX-11 53) SIGRTMAX-10
54) SIGRTMAX-9  55) SIGRTMAX-8  56) SIGRTMAX-7  57) SIGRTMAX-6
58) SIGRTMAX-5  59) SIGRTMAX-4  60) SIGRTMAX-3  61) SIGRTMAX-2
62) SIGRTMAX-1  63) SIGRTMAX

The SIGRTXXX signals are real-time signals, an advanced topic that we don’t cover.

Besides being generated externally, a program can send itself a signal directly, using the Standard C function raise():

#include <signal.h>                                              ISO C

int raise(int sig);

This function sends the signal sig to the calling process. (This action has its uses; we show an example shortly.)

Because raise() is defined by Standard C, it is the most portable way for a process to send itself a signal. There are other ways, which we discuss further on in the chapter.

After putting a signal handler in place, your program proceeds on its merry way. Things don’t get interesting until a signal comes in (for example, the user pressed CTRL-C to interrupt your program or a call to raise() was made).

Upon receipt of the signal, the kernel stops the process wherever it may be. It then simulates a procedure call to the signal handler, passing it the signal number as its sole argument. The kernel arranges things such that a normal return from the signal handler function (either through return or by falling off the end of the function) returns to the point in the program at which the signal happened.

Once a signal has been handled, what happens the next time the same signal comes in? Does the handler remain in place? Or is the signal’s action reset to its default? The answer, for historical reasons, is “it depends.” In particular, the C standard leaves it as implementation defined.

In practice, V7 and traditional System V systems, such as Solaris, reset the signal’s action to the default.

Let’s see a simple signal handler in action under Solaris. The following program, ch10-catchint.c, catches SIGINT. You normally generate this signal by typing CTRL-C at the keyboard.

 1 /* ch10-catchint.c --- catch a SIGINT, at least once. */
 2
 3 #include <signal.h>
 4 #include <string.h>
 5 #include <unistd.h>
 6
 7 /* handler --- simple signal handler. */
 8
 9 void handler(int signum)
10 {
11     char buf[200], *cp;
12     int offset;
13
14     /* Jump through hoops to avoid fprintf(). */
15     strcpy(buf, "handler: caught signal ");
16     cp = buf + strlen(buf); /* cp points at terminating '' */
17     if (signum > 100)       /* unlikely */
18         offset = 3;
19     else if (signum > 10)
20         offset = 2;
21     else
22         offset = 1;
23     cp += offset;
24
25     *cp-- = '';           /* terminate string */
26     while (signum > 0) {    /* work backwards, filling in digits */
27         *cp-- = (signum % 10) + '0';
28         signum /= 10;
29     }
30     strcat(buf, "
");
31     (void) write(2, buf, strlen(buf));
32 }
33
34 /* main --- set up signal handling and go into infinite loop */
35
36 int main(void)
37 {
38     (void) signal(SIGINT, handler);
39
40     for (;;)
41         pause();    /* wait for a signal, see later in the chapter */
42
43     return 0;
44 }

Lines 9–32 define the signal handling function (cleverly named handler()). All this function does is print the caught signal’s number and return. It does a lot of manual labor to generate the message, since fprintf() is not “safe” for calling from within a signal handler. (This is described shortly, in Section 10.4.6, “Additional Caveats,” page 363.)

The main() function sets up the signal handler (line 38) and then goes into an infinite loop (lines 40–41). Here’s what happens when it’s run:

$ ssh solaris.example.com                   Log in to a handy Solaris system
Last login: Fri Sep 19 04:33:25 2003 from 4.3.2.1.
Sun Microsystems Inc.   SunOS 5.9       Generic May 2002
$ gcc ch10-catchint.c                       Compile the program
$ a.out                                     Run it   
^Chandler: caught signal 2                  Type^C, handler is called    
^C                                          Try again, but this time ...
$                                           The program dies

Because V7 and other traditional systems reset the signal’s action to the default, when you wish to receive the signal again in the future, the handler function should immediately reinstall itself:

void handler(int signum)
{
    char buf[200], *cp;
    int offset;

    (void) signal (signum, handler);         /* reinstall handler */

    ... rest of function as before ...
}

4.2 BSD changed the way signal() worked.^[2] On BSD systems, the signal handler remains in place after the handler returns. GNU/Linux systems follow the BSD behavior. Here’s what happens under GNU/Linux:

$ ch10-catchint                                  Run the program
handler: caught signal 2                         Type ^C, handler is called
handler: caught signal 2                         And again...
handler: caught signal 2                         And again!
handler: caught signal 2                         Help!
handler: caught signal 2                         How do we stop this?!
Quit (core dumped)                               ^, generate SIGQUIT. Whew

On a BSD or GNU/Linux system, a signal handler doesn’t need the extra ’signal(signum, handler)’ call to reinstall the handler. However, the extra call also doesn’t hurt anything, since it maintains the status quo.

In fact, POSIX provides a bsd_signal() function, which is identical to signal(), except that it guarantees that the signal handler stays installed:

#include <signal.h>                                              XSI, Obsolescent

void (*bsd_signal(int sig, void (*func) (int)))(int);

This eliminates the portability issues. If you know your program will run only on POSIX systems, you may wish to use bsd_signal() instead of signal().

One caveat is that this function is also marked “obsolescent,” meaning that it can be withdrawn from a future standard. In practice, even if it’s withdrawn, vendors will likely continue to support it for a long time. (As we’ll see, the POSIX sigaction() API provides enough facilities to let you write a workalike version, should you need to.)

More practically, when a signal handler is invoked, it usually means that the program should finish up and exit. It would be annoying if most programs, upon receipt of a SIGINT, printed a message and continued; the point of the signal is that they should stop!

For example, consider the sort program. sort may have created any number of temporary files for use in intermediate stages of the sorting process. Upon receipt of a SIGINT, sort should remove the temporary files and then exit. Here is a simplified version of the signal handler from the GNU Coreutils sort.c:

/* Handle interrupts and hangups. */    Simplified for presentation

static void
sighandler (int sig)
{
  signal (sig, SIG_IGN);                Ignore this signal from now on
  cleanup ();                           Clean up after ourselves
  signal (sig, SIG_DFL);                Restore default action
  raise (sig);                          Now resend the signal
}

Setting the action to SIG_IGN ensures that any further SIGINT signals that come in won’t affect the clean-up action in progress. Once cleanup() is done, resetting the action to SIG_DFL allows the system to dump core if the signal that came in would do so. Calling raise() regenerates the signal. The regenerated signal then invokes the default action, which most likely terminates the program. (We show the full sort.c signal handler later in this chapter.)

The EINTR value for errno (see Section 4.3, “Determining What Went Wrong,” page 86) indicates that a system call was interrupted. While a large number of system calls can fail with this error value, the two most important ones are read() and write(). Consider the following code:

void handler(int signal) { /* handle signals */ }

int main(int argc, char **argv)
{
    signal(SIGINT, handler);
    ...
    while ((count = read(fd, buf, sizeof buf)) > 0) {
        /* process the buffer */
    }
    if (count == 0)
        /* end of file, clean up etc. */
    else if (count == -1)
        /* failure */
    ...
}

Suppose that the system has successfully read (and filled in) part of the buffer when a SIGINT occurs. The read() system call has not yet returned from the kernel to the program, but the kernel decides that it can deliver the signal. handler() is called, runs, and returns into the middle of the read(). What does read() return?

In days of yore (V7, earlier System V systems), read() would return -1 and set errno to EINTR. There was no way to tell that data had been transferred. In this case, V7 and System V act as if nothing happened: No data are transferred to or from the user’s buffer, and the file offset isn’t changed.

4.2 BSD changed this. There were two cases:

Slow devices

Regular files

The BSD behavior is clearly valuable; you can always tell how much data you’ve read.

The POSIX behavior is similar, but not identical, to the original BSD behavior. POSIX indicates that read()^[3] fails with EINTR only if a signal occurred before any data were transferred. Although POSIX doesn’t say anything about “slow devices,” in practice, this condition only occurs on such devices.

Otherwise, if a signal interrupts a partially successful read(), the return is the number of bytes read so far. For this reason (as well as being able handle short files), you should always check the return value from read() and never assume that it read the full number of bytes requested. (The POSIX sigaction() API, described later, allows you to get the behavior of BSD restartable system calls if you want it.)

 1 /* An interface to read and write that retries after interrupts.
 2    Copyright (C) 1993, 1994, 1998, 2002 Free Software Foundation, Inc.
   ...lots of boilerplate stuff omitted ...
56 
57 #ifdef SAFE_WRITE
58 # include "safe-write.h"
59 # define safe_rw safe_write               Create safe_write()
60 # define rw write                         Use write()system call
61 #else
62 # include "safe-read.h"
63 # define safe_rw safe_read                Create safe_read()
64 # define rw read                          Use read()system call
65 # undef const 
66 # define const /* empty */
67 #endif
68 
69 /* Read (write) up to COUNT bytes at BUF from(to) descriptor FD, retrying if 
70    interrupted. Return the actual number of bytes read(written), zero for EOF,
71    or SAFE_READ_ERROR(SAFE_WRITE_ERROR) upon error. */
72 size_t
73 safe_rw (int fd, void const *buf, size_t count)
74 {
75   ssize_t result;
76 
77   /*POSIX limits COUNT to SSIZE_MAX, but we limit it further, requiring 
78     that COUNT <=INT_MAX, to avoid triggering a bug in Tru64 5.1.
79     When decreasing COUNT, keep the file pointer block-aligned.
80     Note that in any case, read(write) may succeed, yet read(write)
81     fewer than COUNT bytes, so the caller must be prepared to handle
82     partial results. */
83   if (count > INT_MAX)
84     count = INT_MAX & ~8191;
85
86   do
87     {
88       result = rw (fd, buf, count);
89     }
90   while (result < 0 && IS_EINTR (errno));
91
92   return (size_t) result;
93 }

 1 /* An interface to write that retries after interrupts.
 2    Copyright (C) 2002 Free Software Foundation, Inc.
   ... lots of boilerplate stuff omitted ...
17
18 #define SAFE_WRITE
19 #include "safe-read.c"

#include <unistd.h>                                              GLIBC

long int TEMP_FAILURE_RETRY(expression);

/* Evaluate EXPRESSION, and repeat as long as it returns -1 with 'errno'
   set to EINTR.  */

# define TEMP_FAILURE_RETRY(expression) 
  (__extension__                                    
    ({ long int __result;                           
       do __result = (long int) (expression);       
       while (__result == -1L && errno == EINTR);   
       __result; }))

size_t safe_read(int fd, void const *buf, size_t count)
{
    ssize_t result;

    /* Limit count as per comment earlier. */
    if (count > INT_MAX)
        count = INT_MAX & ~8191;

    result = TEMP_FAILURE_RETRY(read(fd, buf, count));

    return (size_t) result;
}

So far, handling one signal at a time looks straightforward: install a signal handler in main() and (optionally) have the signal handler reinstall itself (or set the action to SIG_IGN) as the first thing it does.

What happens though if two identical signals come in, right after the other? In particular, what if your system resets the signal’s action to the default, and the second one comes in after the signal handler is called but before it can reinstall itself?

Or, suppose you’re using bsd_signal(), so the handler stays installed, but the second signal is different from the first one? Usually, the first signal handler needs to complete its job before the second one runs, and every signal handler shouldn’t have to temporarily ignore all other possible signals!

Both of these are race conditions. One workaround for these problems is to make signal handlers as simple as possible. You can do this by creating flag variables that indicate that a signal occurred. The signal handler sets the variable to true and returns. Then the main logic checks the flag variable at strategic points:

int sig_int_flag = 0;            /* signal handler sets to true */

void int_handler(int signum)
{
    sig_int_flag = 1;
}

int main(int argc, char **argv)
{
    bsd_signal (SIGINT, int_handler);
    ...program proceeds on...
    if (sig_int_flag) {
        /* SIGINT occurred, handle it */
    }
    ...rest of logic...
}

(Note that this strategy reduces the window of vulnerability but does not eliminate it.)

Standard C introduces a special type—sig_atomic_t—for use with such flag variables. The idea behind the name is that assignments to variables of this type are atomic: That is, they happen in one indivisible action. For example, on most machines, assignment to an int value happens atomically, whereas a structure assignment is likely to be done either by copying all the bytes with a (compiler-generated) loop, or by issuing a “block move” instruction that can be interrupted. Since assignment to a sig_atomic_t value is atomic, once started, it completes before another signal can come in and interrupt it.

Having a special type is only part of the story.sig_atomic_t variables should also be declared volatile:

volatile sig_atomic_t sig_int_flag = 0;  /*signal handler sets to true */
...rest of code as before...

The volatile keyword tells the compiler that the variable can be changed externally, behind the compiler’s back, so to speak. This keeps the compiler from doing optimizations that might otherwise affect the code’s correctness.

Structuring an application exclusively around sig_atomic_t variables is not reliable. The correct way to deal with signals is shown later, in Section 10.7, “Signals for Interprocess Communication,” page 379.

The POSIX standard provides several caveats for signal handlers:

The list in Table 10.2 comes from Section 2.4 of the System Interfaces volume of the 2001 POSIX standard. Many of these functions are advanced APIs not otherwise covered in this volume.

Signals are a complicated topic, and it’s about to get more confusing. So, let’s pause for a moment, take a step back, and summarize what we’ve discussed so far:

Despite the problems, for simple programs, the signal() interface is adequate, and it is still widely used.

What’s wrong with the System V Release 3 APIs? After all, they provide signal blocking, so signals aren’t lost and any given signal can be handled reliably.

The answer is that the API works with only one signal at a time. Programs generally handle more than one signal. And when you’re in the middle of handling one signal, you don’t want to have to worry about handling another one. (Suppose you’ve just answered your office phone when your cell phone starts ringing: You’d prefer to have the phone system tell your caller you’re on another line and you’ll be there shortly, instead of having to do it yourself.)

With the sigset() API, each signal handler would have to temporarily block all the other signals, do its job, and then unblock them. The problem is that in the interval between any two calls to sighold(), a not-yet-blocked signal could come up. The scenario is rife, once again, with race conditions.

The solution is to make it possible to work with groups of signals atomically, that is, with one system call. You effect this by working with signal sets and the process signal mask.

The process signal mask is a list of signals that a process currently has blocked. The strength of the POSIX API is that the process signal mask can be manipulated atomically, as a whole.

The process signal mask is represented programmatically with a signal set. This is the sigset_t type. Conceptually, it’s just a bitmask, with 0 and 1 values in the mask representing a particular signal’s absence or presence in the mask:

/* Signal mask manipulated directly.  DO NOT DO THIS! */
int mask = (1 << SIGHUP) | (1 << SIGINT);   /* bitmask for SIGHUP and SIGINT */

However, because a system can have more signals than can be held in a single int or long and because heavy use of the bitwise operators is hard to read, several APIs exist to manipulate signal sets:

#include <signal.h>                                              POSIX

int sigemptyset(sigset_t *set);
int sigfillset(sigset_t *set);
int sigaddset(sigset_t *set, int signum);
int sigdelset(sigset_t *set, int signum);
int sigismember(const sigset_t *set, int signum);

The functions are as follows:

int sigemptyset (sigset_t *set)

int sigfillset (sigset_t *set)

int sigaddset (sigset_t *set, int signum)

int sigdelset (sigset_t *set, int signum)

int sigismember (const sigset_t *set, int signum)

You must always call one of sigemptyset() or sigfillset() before doing anything else with a sigset_t variable. Both interfaces exist because sometimes you want to start out with an empty set and then just work with one or two signals, and other times you want to work with all signals, possibly taking away one or two.

The process signal mask starts out empty—initially, no signals are blocked. (This is a simplification; see Section 10.9, “Signals Across fork() and exec(),” page 398.) Three functions let you work directly with the process signal mask:

#include <signal.h>                                              POSIX

int sigprocmask(int how, const sigset_t *set, sigset_t *oldset);
int sigpending(sigset_t *set);
int sigsuspend(const sigset_t *set);

The functions are as follows:

int sigprocmask(int how, const sigset_t *set, sigset_t *oldset)

int sigpending(sigset_t *set)

int sigsuspend(const sigset_t *set)

Finally, we’re ready to look at the sigaction() function. This function is complicated, and we intentionally omit many details that are only for advanced uses. The POSIX standard and the sigaction(2) manpage provide full details, although you must carefully read both to fully absorb everything.

#include <signal.h>                                              POSIX

int sigaction(int signum, const struct sigaction *act, struct sigaction *oldact);

The arguments are as follows:

int signum

const struct sigaction *act

struct sigaction *oldact

Thus, sigaction() both sets the new handler and retrieves the old one, in one shot. The struct sigaction looks like this:

/* NOTE: Order in struct may vary. There may be other fields too! */
struct sigaction {
    sigset_t sa_mask;                                   Additional signals to block
    int sa_flags;                                       Control behavior
    void (*sa_handler) (int);                           May be union with sa_sigaction
    void (*sa_sigaction) (int, siginfo_t *, void *);    May be union with sa_handler
}

The fields are as follows:

sigset_t sa_mask

int sa_flags

void (*sa_handler) (int)

void (*sa_sigaction) (int, siginfo_t *, void *)

Which of act->sa_handler and act->sa_sigaction is used depends on the SA_SIGINFO flag in act->sa_flags. When present, act->sa_sigaction is used; otherwise, act->sa_handler is used. Both POSIX and the GNU/Linux manpage point out that these two fields may overlap in storage (that is, be part of a union). Thus, you should never use both fields in the same struct sigaction.

The sa_flags field is the bitwise OR of one or more of the flag values listed in Table 10.3.

When the SA_SIGINFO flag is set in act->sa_flags, then the act->sa_sigaction field is a pointer to a function declared as follows:

void action_handler(int sig, siginfo_t *info, void *context)
{
    /* handler body here */
}

The siginfo_t structure provides a wealth of information about the signal:

/* POSIX 2001 definition.  Actual contents likely to vary across systems. */
typedef struct {
    int si_signo;            /* signal number */
    int si_errno;            /* <errno.h> value if an error */
    int si_code;             /* signal code; see text */
    pid_t si_pid;            /* process ID of process that sent signal */
    uid_t si_uid;            /* real UID of sending process */
    void *si_addr;           /* address of instruction that faulted */
    int si_status;           /* exit value, may include death-by-signal */
    long si_band;            /* band event for SIGPOLL/SIGIO */
    union sigval si_value;   /* signal value (advanced) */
} siginfo_t;

The si_signo, si_code, and si_value fields are available for all signals. The other fields can be members of a union and thus should be used only for the signals for which they’re defined. There may also be other fields in the siginfo_t structure.

Almost all the fields are for advanced uses. The full details are in the POSIX standard and in the sigaction(2) manpage. However, we can describe a straightforward use of the si_code field.

For SIGBUS, SIGCHLD, SIGFPE, SIGILL, SIGPOLL, SIGSEGV, and SIGTRAP, the si_code field can take on any of a set of predefined values specific to each signal, indicating the cause of the signal. Frankly, the details are a bit overwhelming; everyday code doesn’t really need to deal with them (although we’ll look at the values for SIGCHLD later on). For all other signals, the si_code member has one of the values in Table 10.4.

In particular, the SI_USER value is useful; it allows a signal handler to tell if the signal was sent by raise() or kill() (described later). You can use this information to avoid calling raise() or kill() a second time.

The third argument to a three-argument signal handler, void *context, is an advanced feature, not otherwise discussed in this volume.

Finally, to see sigaction() in use, examine the full text of the signal handler for sort.c:

2074 static void
2075 sighandler (int sig)
2076 {
2077 #ifndef SA_NOCLDSTOP                         On old style system ...
2078   signal (sig, SIG_IGN);                     – Use signal() to ignore sig
2079 #endif                                       – Otherwise, sig automatically blocked
2080
2081   cleanup ();                                Run cleanup code
2082
2083 #ifdef SA_NOCLDSTOP                          On POSIX style system ...
2084   {
2085     struct sigaction sigact;
2086
2087     sigact.sa_handler = SIG_DFL;             – Set action to default
2088     sigemptyset (&sigact.sa_mask);           – No additional signals to block
2089     sigact.sa_flags = 0;                     – No special action to take
2090     sigaction (sig, &sigact, NULL);          – Put it in place
2091   }
2092 #else                                        On old style system ...
2093   signal (sig, SIG_DFL);                     – Set action to default
2094 #endif
2095
2096   raise (sig);                               Resend the signal
2097 }

Here is the code in main() that puts the handler in place:

2214 #ifdef SA_NOCLDSTOP                          On a POSIX system ...
2215   {
2216     unsigned i;
2217     sigemptyset (&caught_signals);
2218     for (i = 0; i < nsigs; i++)              – Block all signals
2219       sigaddset (&caught_signals, sigs[i]);
2220     newact.sa_handler = sighandler;          – Signal handling function
2221     newact.sa_mask = caught_signals;         — Set process signal mask for handler
2222     newact.sa_flags = 0;                     – No special flags
2223   }
2224 #endif
2225
2226   {
2227     unsigned i;
2228     for (i = 0; i < nsigs; i++)              For all signals ...
2229       {
2230         int sig = sigs[i];
2231 #ifdef SA_NOCLDSTOP
2232         sigaction (sig, NULL, &oldact);      – Retrieve old handler
2233         if (oldact.sa_handler != SIG_IGN)    – If not ignoring this signal
2234           sigaction (sig, &newact, NULL);    – Install our handler
2235 #else
2236         if (signal (sig, SIG_IGN) != SIG_IGN)
2237           signal (sig, sighandler);          – Same logic with old API
2238 #endif
2239       }
2240   }

We note that lines 2216–2219 and 2221 could be replaced with the single call:

sigfillset(& newact.sa_mask);

We don’t know why the code is written the way it is.

Also of interest are lines 2233–2234 and 2236–2237, which show the correct way to check whether a signal is being ignored and to install a handler only if it’s not.

The sigpending() system call, described earlier, lets you retrieve the set of signals that are pending, that is, those that have come in, but are not yet delivered because they were blocked:

#include <signal.h>                                               POSIX

int sigpending(sigset_t *set);

Besides unblocking the pending signals so that they get delivered, you may choose to ignore them. Setting the action for a pending signal to SIG_IGN causes the pending signal to be discarded (even if it was blocked). Similarly, for those signals for which the default action is to ignore the signal, setting the action to SIG_DFL causes such a pending signal to also be discarded.

As a convenience, the siginterrupt() function can be used to make functions interruptible for a particular signal or to make them restartable, depending on the value of the second argument. The declaration is:

#include <signal.h>                                               XSI

int siginterrupt(int sig, int flag);

According to the POSIX standard, the behavior of siginterrupt() is equivalent to the following code:

int siginterrupt(int sig, int flag)
{
    int ret;
    struct sigaction act;

    (void) sigaction(sig, NULL, &act);         Retrieve old setting

    if (flag)                                  If flag is true ...
        act.sa_flags &= ~SA_RESTART;           Disable restarting
    else                                       Otherwise ...
        act.sa_flags |= SA_RESTART;            Enable restarting

    ret = sigaction(sig, &act, NULL);          Put new setting in place
    return ret;                                Return result
}

The return value is 0 on success or -1 on error.

The traditional Unix function for sending a signal is named kill(). The name is something of a misnomer; all it does is send a signal. (Often, the result is that the signal’s recipient dies, but that need not be true. However, it’s way too late now to change the name.) The killpg() function sends a signal to a specific process group. The declarations are:

#include <sys/types.h>                                               POSIX
#include <signal.h>

int kill(pid_t pid, int sig);
int killpg(int pgrp, int sig);                                       XSI

The sig argument is either a signal name or 0. In the latter case, no signal is sent, but the kernel still performs error checking. In particular, this is the correct way to verify that a given process or process group exists, as well as to verify that you have permission to send signals to the process or process group. kill() returns 0 on success and -1 on error; errno then indicates the problem.

The rules for the pid value are a bit complicated:

The meanings of pid for kill() are similar to those of waitpid() (see Section 9.1.6.1, “Using POSIX Functions: wait() and waitpid(),” page 306).

The Standard C function raise() is essentially equivalent to

int raise(int sig)
{
    return kill(getpid(), sig);
}

The C standards committee chose the name raise() because C also has to work in non-Unix environments, and kill() was considered specific to Unix. It was also a good opportunity to use a more descriptive name for the function.

killpg() sends a signal to a process group. As long as the pgrp value is greater than 1, it’s equivalent to ’kill(-pgrp, sig)’. The GNU/Linux killpg(2) manpage states that if pgrp is 0, the signal is sent to the sending processes’s process group. (This is the same as kill().)

As you might imagine, you cannot send signals to arbitrary processes (unless you are the superuser, root). For ordinary users, the real or effective UID of the sending process must match the real or saved set-user-ID of the receiving process. (The different UIDs are described in Section 11.1.1, “Real and Effective IDs,” page 405.)

However, SIGCONT is a special case: As long as the receiving process is a member of the same session as the sender, the signal will go through. (Sessions were described briefly in Section 9.2.1, “Job Control Overview,” page 312.) This special rule allows a job control shell to continue a stopped descendant process, even if that stopped process is running with a different user ID.

The System V Release 3 API was intended to remedy the various problems presented by the original V7 signal APIs. The notion of signal blocking, in particular, is an important additional concept.

However, those APIs didn’t go far enough, since they worked on only one signal at a time, leaving wide open plenty of windows through which undesired signals could arrive. The POSIX APIs, by working atomically on multiple signals (the process signal mask, represented programmatically by the sigset_t type), solves this problem, closing the windows.

The first set of functions we examined manipulate sigset_t values: sigfillset(), sigemptyset(), sigaddset(), sigdelset(), and sigismember().

The next set works with the process signal mask: sigprocmask() sets and retrieves the process signal mask. sigpending() retrieves the set of pending signals, and sigsuspend() puts a process to sleep, temporarily replacing the process signal mask with the one in its parameter.

The POSIX sigaction() API is (severely) complicated by the need to supply

The siginterrupt() function is a convenience API for enabling or disabling restartable system calls for a given signal.

Finally, kill() and killpg() can be used to send signals, not just to the current process but to other processes as well (permissions permitting, of course).

It is often necessary to write programs of the form

while (some condition isn't true) {
    wait for a while
}

This need comes up frequently in shell scripting, for example, to wait until a particular user has logged in:

until who | grep '^arnold' > /dev/null
do
    sleep 10
done

Two mechanisms, one lower level and one higher level, let a running process know when a given number of seconds have passed.

#include <unistd.h>                                              POSIX

unsigned int alarm(unsigned int seconds);

#include <unistd.h>                                              POSIX

unsigned int sleep(unsigned int seconds);

Several signals are used to implement job control—the ability to start and stop jobs, and move them to and from the background and foreground. At the user level, you have undoubtedly done this: using CTRL-Z to stop a job, bg to put it in the background, and occasionally using fg to move a background or stopped job into the foreground.

Section 9.2.1, “Job Control Overview,” page 312, describes generally how job control works. This section completes the overview by describing the job control signals, since you may occasionally wish to catch them directly:

SIGTSTP

SIGSTOP

SIGTTIN, SIGTTOU

SIGCONT

When a process is stopped, any other signals sent to it become pending. The exception to this is SIGKILL, which is always delivered to the process and which cannot be caught, blocked, or ignored. Assuming that signals besides SIGKILL have been sent, upon receipt of a SIGCONT, the pending signals are delivered and the process then continues execution after they’ve been handled.

As described in Section 9.1.1, “Creating a Process: fork(),” page 284, one side effect of calling fork() is the creation of parent-child relationships among processes. A parent process can wait for one or more of its children to die and recover the child’s exit status by one of the wait() family of system calls.

Dead child processes that haven’t been waited for are termed zombies. Normally, every time a child process dies, the kernel sends a SIGCHLD signal to the parent process.^[6] The default action is to ignore this signal. In this case, zombie processes accrue until the parent does a wait() or until the parent itself dies. In the latter case, the zombie children are reparented to the init system process (PID 1), which reaps them as part of its normal work. Similarly, active children are also reparented to init and will be reaped when they exit.

SIGCHLD is used for more than death-of-children notification. Any time a child is stopped (by one of the job control signals discussed earlier), SIGCHLD is also sent to the parent. The POSIX standard indicates that SIGCHLD “may be sent” when a child is continued as well; apparently there are differences among historical Unix systems.

A combination of flags for the sa_flags field in the struct sigaction, and the use of SIG_IGN as the action for SIGCHLD allows you to change the way the kernel deals with children stopping, continuing, or dying.

As with signals in general, the interfaces and mechanisms described here are complicated because they have evolved over time.

/* Old style: */                   /* New style: */
                                   struct sigaction sa;
                                   sa.sa_handler = SIG_IGN;
signal (SIGCHLD, SIG_IGN);         sa.sa_flags = SA_NOCLDWAIT;
                                   sigemptyset (& sa.sa_mask);
                                   sigaction (SIGCHLD, & sa, NULL);

  1  /* ch10-reap1.c --- demonstrate SIGCHLD management, using a loop */
  2
  3  #include <stdio.h>
  4  #include <errno.h>
  5  #include <signal.h>
  6  #include <string.h>
  7  #include <sys/types.h>
  8  #include <sys/wait.h>
  9
 10  #define MAX_KIDS 42
 11  #define NOT_USED -1
 12
 13  pid_t kids [MAX_KIDS];
 14  size_t nkids = 0;

  16  /* format_num --- helper function since can't use [sf]printf() */
  17
  18  const char *format_num(int num)
  19  {
  20  #define NUMSIZ 30
  21      static char buf[NUMSIZ];
  22      int i;
  23
  24      if (num <= 0) {
  25          strcpy(buf, "0");
  26          return buf;
  27      }
  28
  29      i = NUMSIZ - 1;
  30      buf[i--] = '';
  31
  32      /* Generate digits backwards into string. */
  33      do {
  34          buf[i--] = (num % 10) + '0';
  35          num /= 10;
  36      } while (num > 0);
  37
  38      return & buf[i+1];
  39  }

  41  /* childhandler --- catch SIGCHLD, reap all available children */
  42
  43  void childhandler(int sig)
  44  {
  45      int status, ret;
  46      int i;
  47      char buf[100];
  48      static const char entered[] = "Entered childhandler
";
  49      static const char exited[] = "Exited childhandler
";
  50
  51      write(1, entered, strlen(entered));
  52      for (i = 0; i < nkids; i++) {
  53          if (kids[i] == NOT_USED)
  54              continue;
  55
  56      retry:
  57          if ((ret = waitpid(kids[i], & status, WNOHANG)) == kids[i]) {
  58              strcpy(buf,"	reaped process ");
  59              strcat(buf, format_num(ret));
  60              strcat(buf, "
");
  61              write(1, buf, strlen(buf));
  62              kids[i] = NOT_USED;
  63          } else if (ret == 0) {
  64              strcpy(buf, "	pid "); 
  65              strcat(buf, format_num(kids[i])); 
  66              strcat(buf, "not available yet
"); 
  67              write(1, buf, strlen(buf));
  68          } else if (ret == -1 && errno == EINTR) {
  69              write(1, "	retrying
", 10);
  70              goto retry;
  71          } else {
  72              strcpy(buf, "	waitpid() failed: ");
  73              strcat(buf, strerror(errno));
  74              strcat(buf, "
");
  75              write(1, buf, strlen(buf));
  76          }
  77      }
  78      write(1, exited, strlen(exited));
  79  } 

  81  /* main --- set up child-related information and signals, create children */
  82
  83  int main(int argc, char **argv)
  84  {
  85      struct sigaction sa;
  86      sigset_t childset, emptyset;
  87      int i;
  88
  89      for (i = 0; i < nkids; i++)
  90          kids[i] = NOT_USED;
  91
  92      sigemptyset (& emptyset);
  93
  94      sa.sa_flags = SA_NOCLDSTOP;
  95      sa.sa_handler = childhandler;
  96      sigfillset (& sa.sa_mask); /* block everything when handler runs */
  97      sigaction(SIGCHLD, & sa, NULL);
  98
  99      sigemptyset(& childset);
 100      sigaddset (& childset, SIGCHLD);
 101
 102      sigprocmask (SIG_SETMASK, & childset, NULL); /* block it in main code */
 103
 104      for (nkids = 0; nkids < 5; nkids++) {
 105          if ((kids[nkids] = fork()) == 0) {
 106              sleep(3);
 107              _exit(0);
 108          }
 109      }
 110
 111      sleep(5); /* give the kids a chance to terminate */
 112
 113      printf("waiting for signal
");
 114      sigsuspend (& emptyset);
 115
 116      return 0;
 117  }

$ ch10-reap1                                              Run the program
waiting for signal
Entered childhandler
        reaped process 23937
        reaped process 23938
        reaped process 23939
        reaped process 23940
        reaped process 23941
Exited childhandler

  1  /* ch10-reap2.c --- demonstrate SIGCHLD management, one signal per child */
  2
     ...unchanged code omitted...
 12
 13  pid_t kids [MAX_KIDS];
 14  size_t nkids = 0;
 15  size_t kidsleft = 0;                /* <<< Added */
 16
     ...unchanged code for format_num() omitted...
 41
 42  /* childhandler --- catch SIGCHLD, reap all available children */
 43
 44  void childhandler (int sig)
 45  {
 46      int status, ret;
 47      int i;
 48      char buf[100];
 49      static const char entered[] = "Entered childhandler
";
 50      static const char exited[] = "Exited childhandler
";
 51
 52      write(1, entered, strlen (entered));
 53      for (i = 0; i < nkids; i++) {
 54          if (kids[i] == NOT_USED)
 55              continue;
 56
 57      retry:
 58          if ((ret = waitpid(kids[i], & status, WNOHANG)) == kids[i]) {
 59              strcpy(buf, "	reaped process");
 60              strcat(buf, format_num(ret));
 61              strcat(buf, "
");
 62              write(1, buf, strlen(buf));
 63              kids[i] = NOT_USED;
 64              kidsleft--;          /* <<< Added */
 65          } else if (ret == 0) {
     ...unchanged code omitted...
 80      write(1, exited, strlen(exited));
 81  }

 83  /* main --- set up child-related information and signals, create children */
 84
 85  int main(int argc, char **argv)
 86  {
     ...unchanged code omitted...
100
101      sigemptyset (& childset);
102      sigaddset(& childset, SIGCHLD);
103
104  /*  sigprocmask(SIG_SETMASK, & childset, NULL); /* block it in main code */
105
106      for (nkids = 0; nkids < 5; nkids++) {
107          if ((kids[nkids] = fork ()) == 0) {
108              sleep(3);
109              _exit(0);
110          }
111          kidsleft++;               /* <<< Added */
112      }
113
114  /*  sleep(5); /* give the kids a chance to terminate */
115
116      while (kidsleft > 0) {       /* <<< Added */
117          printf("waiting for signals
");
118          sigsuspend(& emptyset);
119      }                            /* <<< Added */
120
121      return 0;
122  }

$ uname -a                                      Display system version
Linux example1 2.4.20-8 #1 Thu Mar 13 17:54:28 EST 2003 i686 i686 i386 GNU/Linux
$ ch10-reap2                                    Run the program
waiting for signals
Entered childhandler                            Reap one child
        reaped process 2702
        pid 2703 not available yet
        pid 2704 not available yet
        pid 2705 not available yet
        pid 2706 not available yet
Exited childhandler
waiting for signals
Entered childhandler                            And the next
        reaped process 2703
        pid 2704 not available yet
        pid 2705 not available yet
        pid 2706 not available yet
Exited childhandler
waiting for signals
Entered childhandler                            And so on
        reaped process 2704
        pid 2705 not available yet
        pid 2706 not available yet
Exited childhandler
waiting for signals
Entered childhandler
        reaped process 2705
        pid 2706 not available yet
Exited childhandler
waiting for signals
Entered childhandler
        reaped process 2706
Exited childhandler

$ uname -a                                      Display system version
Linux example2 2.4.22-1.2115.nptl #1 Wed Oct 29 15:42:51 EST
        2003 i686 i686 i386 GNU/Linux
$ ch10-reap2                                    Run the program
waiting for signals
Entered childhandler                            Signal handler only called once
        reaped process 9564
        reaped process 9565
        reaped process 9566
        reaped process 9567
        reaped process 9568
Exited childhandler

  1  /* ch10-status.c --- demonstrate SIGCHLD management, use 3 argument handler */
  2
  3  #include <stdio.h>
  4  #include <errno.h>
  5  #include <signal.h>
  6  #include <string.h>
  7  #include <sys/types.h>
  8  #include <sys/wait.h>
  9
 10  void manage (siginfo_t *si);
 11
     ... unchanged code for format_num() omitted ...

 37  /* childhandler --- catch SIGCHLD, reap just one child */
 38
 39  void childhandler (int sig, siginfo_t *si, void *context)
 40  {
 41      int status, ret;
 42      int i;
 43      char buf[100];
 44      static const char entered[] = "Entered childhandler
";
 45      static const char exited[] = "Exited childhandler
";
 46
 47      write(1, entered, strlen(entered));
 48  retry:
 49      if ((ret = waitpid(si->si_pid, & status, WNOHANG)) == si->si_pid) {
 50          strcpy(buf, "	reaped process");
 51          strcat(buf, format_num(si->si_pid));
 52          strcat(buf, "
");
 53          write(1, buf, strlen(buf));
 54          manage(si);         /* deal with what happened to it */
 55      } else if (ret > 0) {
 56          strcpy(buf, "	reaped unexpected pid ");
 57          strcat(buf, format_num(ret));
 58          strcat(buf, "
");
 59          write(1, buf, strlen(buf));
 60          goto retry;     /* why not? */
 61      } else if (ret == 0) {
 62          strcpy(buf, "	pid ");
 63          strcat(buf, format_num(si->si_pid));
 64          strcat(buf, " changed status
");
 65          write(1, buf, strlen(buf));
 66          manage(si);         /* deal with what happened to it */
 67      } else if (ret == -1 && errno == EINTR) {
 68          write(1, "	retrying
", 10);
 69          goto retry;
 70      } else {
 71          strcpy(buf, "	waitpid() failed: ");
 72          strcat(buf, strerror(errno));
 73          strcat(buf, "
");
 74          write(1, buf, strlen(buf));
 75      }
 76
 77      write(1, exited, strlen(exited));
 78  }

 80  /* child --- what to do in the child */
 81
 82  void child(void)
 83  {
 84      raise(SIGCONT);     /* should be ignored */
 85      raise(SIGSTOP);     /* go to sleep, parent wakes us back up */
 86      printf("	---> child restarted <---
");
 87      exit(42);           /* normal exit, let parent get value */
 88  }

 90  /* main --- set up child-related information and signals, create child */
 91
 92  int main(int argc, char **argv)
 93  {
 94      pid_t kid;
 95      struct sigaction sa;
 96      sigset_t childset, emptyset;
 97
 98      sigemptyset (& emptyset);
 99
100      sa.sa_flags = SA_SIGINFO;
101      sa.sa_sigaction = childhandler;
102      sigfillset(& sa.sa_mask); /* block everything when handler runs */
103      sigaction(SIGCHLD, & sa, NULL);
104
105      sigemptyset(& childset);
106      sigaddset(& childset, SIGCHLD);
107
108      sigprocmask(SIG_SETMASK, & childset, NULL); /* block it in main code */
109
110      if ((kid = fork()) == 0)
111          child();
112
113      /* parent executes here */
114      for (;;) {
115          printf("waiting for signals
");
116          sigsuspend(& emptyset);
117      }
118
119      return 0;
120  }

123  /* manage --- deal with different things that could happen to child */
124
125  void manage(siginfo_t *si)
126  {
127      char buf[100];
128
129      switch (si->si_code) {
130      case CLD_STOPPED:
131          write(1, "	child stopped, restarting
", 27);
132          kill(si->si_pid, SIGCONT);
133          break;
134
135       case CLD_CONTINUED: /* not sent on Linux */
136           write(1, "	child continued
", 17);
137           break;
138
139       case CLD_EXITED:
140           strcpy(buf, "	child exited with status ");
141           strcat(buf, format_num(si->si_status));
142           strcat(buf, "
");
143           write(1, buf, strlen(buf));
144           exit(0); /* we're done */
145           break;
146
147       case CLD_DUMPED:
148           write(1, "	child dumped
", 14);
149           break;
150
151       case CLD_KILLED:
152           write(1, "	child killed
", 14);
153           break;
154
155       case CLD_TRAPPED:
156           write(1, "	child trapped
", 15);
157           break;
158       }
159   }

$ ch10-status                                      Run the program
waiting for signals
Entered childhandler                               Signal handler entered
        pid 24279 changed status
        child stopped, restarting                  Handler takes action
Exited childhandler
waiting for signals
        ---> child restarted <---                  From the child
Entered childhandler
        reaped process 24279                       Parent's handler reaps child
        child exited with status 42