Part 3 of 7 · 3 min read
Clean shutdown
Think of a shop at closing time. A polite request, "closing in five minutes", lets the staff finish serving, count the till and lock up. A power cut leaves customers at the counter and the till uncounted. The analogy stops in one place: a shop has staff who understand the request, and a program understands SIGTERM only if its author wrote a handler.
In plain words: The program below installs a handler for SIGTERM with sigaction. The handler only sets a flag, because very few functions are safe to call inside a handler (those called async-signal-safe; printf and malloc are not). The main loop waits with pause and, when the flag is set, prints a message and returns 0.
#include <signal.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>
static volatile sig_atomic_t stop;
static void on_term(int sig) { (void)sig; stop = 1; } /* only set a flag */
int main(void) {
struct sigaction sa;
memset(&sa, 0, sizeof sa);
sa.sa_handler = on_term;
sigaction(SIGTERM, &sa, NULL);
printf("running, pid %d\n", (int)getpid());
fflush(stdout);
while (!stop) pause(); /* wait for a signal */
puts("SIGTERM received: flushing data and exiting cleanly");
return 0;
}
Three runs, each followed by the exit status:
$ ./graceful & ; kill -TERM $! exit status 0 output: SIGTERM received: flushing data and exiting cleanly
$ ./graceful & ; kill -KILL $! exit status 137 (shell: Killed)
$ ./graceful & ; kill -INT $! exit status 130 (shell: Interrupt)
A worked example. With SIGTERM the handler ran, the program printed its message and returned 0: a clean shutdown, in which a real service would close connections, flush buffers and remove temporary files. With SIGKILL the kernel ended it at once: no handler, no message, status 137 = 128 + 9. With SIGINT there was no handler, so the default action ended it with status 130 = 128 + 2. A service manager that stops a service sends SIGTERM, waits for a grace period, and sends SIGKILL if the process is still there, so a service without a handler loses its unsaved work in every stop.
The key lines. A handler should do the least: set a flag or write to a pipe, and let the main code do the work. The flag has the type volatile sig_atomic_t, which makes the read and write safe against the signal.
Async-signal-safe function
An async-signal-safe function is one that may be called from inside a signal handler without risk, because it does not depend on state that the interrupted code may be changing (such as the lock inside malloc or printf). The list is in man 7 signal-safety.
Example: write is async-signal-safe, and printf is not.
Common mistake
Calling printf or malloc in a signal handler. If the signal arrives while the main code is inside malloc, the handler may wait for a lock that the interrupted code holds, and the program hangs, or it corrupts the heap (Level 7).
Check yourself:
1. What did the handler do, and why so little?
2. Which exit status did SIGKILL give, and why?
3. What does a service manager do when SIGTERM is not enough?