Introduction

SIGTERM is the standard Unix signal for "please terminate." Unlike SIGKILL, it gives the process a chance to clean up, flush state, close sockets, and stop accepting new work before exiting.

Handling SIGTERM gracefully is less about catching the signal and immediately calling exit(). The better pattern is to treat it as a shutdown request, flip the program into a draining state, finish critical cleanup, and then exit normally.

Treat SIGTERM as a Shutdown Request

In C, a basic signal handler often just sets a global flag:

1#include <signal.h>
2#include <stdatomic.h>
3#include <stdio.h>
4#include <unistd.h>
5
6static volatile sig_atomic_t stop_requested = 0;
7
8void handle_sigterm(int signum) {
9    (void)signum;
10    stop_requested = 1;
11}
12
13int main(void) {
14    signal(SIGTERM, handle_sigterm);
15
16    while (!stop_requested) {
17        printf("working...\n");
18        sleep(1);
19    }
20
21    printf("shutting down cleanly\n");
22    return 0;
23}

The important idea is that the signal handler itself does almost nothing. It records the request, and the main control flow performs the real shutdown work safely.

Keep the Handler Minimal

Signal handlers run asynchronously, which means most ordinary application code is not safe to execute inside them. That is why the minimal-handler pattern is preferred:

• set a flag
• notify a self-pipe or eventfd if needed
• let the main loop do the actual shutdown work

This is especially important in network servers and multithreaded applications. The process usually needs to:

• stop accepting new requests
• finish or cancel in-flight work
• flush logs or state
• close resources in a defined order

Those steps belong in normal program flow, not inside the handler body.

Graceful Shutdown in Higher-Level Runtimes

The same principle applies outside C. For example, in Python:

1import signal
2import time
3
4stop_requested = False
5
6def handle_sigterm(signum, frame):
7    global stop_requested
8    stop_requested = True
9
10signal.signal(signal.SIGTERM, handle_sigterm)
11
12while not stop_requested:
13    print("working...")
14    time.sleep(1)
15
16print("clean shutdown")

This is a simple example, but the same pattern scales to bigger services: signal arrives, application switches to shutdown mode, normal code finishes cleanup.

Design the Shutdown Sequence Explicitly

Good graceful shutdown logic usually answers these questions:

• should new work be rejected immediately
• should current work finish or be canceled
• what state must be persisted before exit
• how long should shutdown wait before forcing termination

That sequence matters more than the signal API itself. Catching SIGTERM is easy. Shutting down correctly is the real engineering work.

Common Pitfalls

The biggest mistake is doing too much work directly inside the signal handler. Most functions are not async-signal-safe, so that can create subtle bugs or deadlocks.

Another common issue is treating SIGTERM exactly like SIGKILL. If you call _exit() immediately, you lose the chance to clean up and defeat the point of graceful shutdown.

It is also easy to forget that shutdown may happen during active requests, open transactions, or partial writes. A graceful handler needs a real draining policy, not just a log message.

Finally, do not assume one signal handler is enough for every runtime. The signal semantics are OS-level, but the cleanup strategy depends on the application model.

Summary

• 'SIGTERM is a request to terminate gracefully, not a forced kill.'
• Keep the signal handler minimal and let the main flow perform cleanup.
• Use a shutdown flag or notification mechanism to trigger draining behavior.
• Define what should happen to in-flight work before exit.
• The quality of the shutdown sequence matters more than the signal catch itself.