C Reference ยท POSIX and Systems
C sigaction() function
Reference for sigaction(), sigprocmask() and sigsuspend(): install signal handlers reliably, block signals, wait without races, and keep handlers async-signal-safe.
sigaction() is the POSIX way to install a signal handler. It does what signal() does, but with precisely defined behavior: you decide whether the handler stays installed, which other signals are blocked while it runs, and whether interrupted system calls restart. Portable programs on Unix should use sigaction and leave signal for the simplest cases.
Around sigaction sit a few related calls. sigprocmask() (or pthread_sigmask() in threaded programs) blocks signals so they stay pending instead of arriving at an inconvenient moment. sigsuspend() atomically unblocks signals and sleeps until one arrives, which closes the race between checking a flag and going to sleep.
struct sigaction sa; memset(&sa, 0, sizeof sa); sa.sa_handler = on_signal; sigemptyset(&sa.sa_mask); sigaction(SIGINT, &sa, NULL);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
int sigaction(int signum, const struct sigaction *restrict act, struct sigaction *restrict oldact); struct sigaction { void (*sa_handler)(int); void (*sa_sigaction)(int, siginfo_t *, void *); sigset_t sa_mask; int sa_flags; }; int sigemptyset(sigset_t *set); int sigfillset(sigset_t *set); int sigaddset(sigset_t *set, int signo); int sigdelset(sigset_t *set, int signo); int sigismember(const sigset_t *set, int signo); int sigprocmask(int how, const sigset_t *set, sigset_t *oldset); int sigpending(sigset_t *set); int sigsuspend(const sigset_t *mask);
| Name | Description |
|---|---|
signum |
The signal to handle, such as SIGINT, SIGTERM or SIGUSR1. SIGKILL and SIGSTOP cannot be caught. |
act |
The new action. NULL only queries the current one. |
oldact |
Receives the previous action. May be NULL. |
sa_handler |
A function, SIG_IGN (ignore) or SIG_DFL (default action). |
sa_sigaction |
A three-argument handler used when SA_SIGINFO is set; it receives details such as the sender in siginfo_t. Do not set both handler fields. |
sa_mask |
Extra signals blocked while the handler runs. The signal being handled is blocked too, unless SA_NODEFER is set. |
sa_flags |
Options: SA_RESTART (restart interrupted system calls), SA_SIGINFO, SA_NODEFER, SA_RESETHAND (one-shot), SA_NOCLDSTOP. |
how |
For sigprocmask: SIG_BLOCK, SIG_UNBLOCK or SIG_SETMASK. |
Returns: 0 on success, -1 with errno set on error (EINVAL for an invalid signal or an attempt to catch SIGKILL or SIGSTOP). sigismember returns 1, 0 or -1. sigsuspend always returns -1 with errno equal to EINTR.
Errors / undefined behavior: calling a function that is not async-signal-safe from a handler, or reading a non-volatile sig_atomic_t variable that a handler writes, is undefined behavior.
Usage notes
- Zero the struct first.
memset(&sa, 0, sizeof sa)makes suresa_flagsand any extra fields start clean. Then callsigemptyset(&sa.sa_mask). - Keep handlers tiny. Set a
volatile sig_atomic_tflag and return; do the real work in the main loop. Only async-signal-safe functions may be called from a handler:write,_exit,signal,sigactionand a short list of others.printf,mallocandfreeare not safe. - Save and restore
errnoin a handler that calls anything that may change it. SA_RESTARTmakesread,write,acceptand similar calls resume after a handler, instead of failing withEINTR. Without it, loops around such calls must handleEINTR.- No lost wake-ups. Checking a flag and then calling
pause()has a race: the signal can arrive in between and you sleep forever. Block the signal, test the flag, and usesigsuspend, as in the second example. - Signals and threads. Signal dispositions are per process, but the mask is per thread. In a threaded program, block signals in all threads and dedicate one thread to
sigwait, or usepthread_sigmask. signal()differences. Under-std=c23with glibc,signal()has one-shot semantics, whilesigactionbehaves the same everywhere.- Windows has only the ISO
signal();sigactionis POSIX.