Skip to content
Tutorials Center
My learning

Topics

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.

C
struct sigaction sa;
memset(&sa, 0, sizeof sa);
sa.sa_handler = on_signal;
sigemptyset(&sa.sa_mask);
sigaction(SIGINT, &sa, NULL);

Try it

C Install a handler, block a signal, then unblock 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.

C Sleep until a timer signal, without a race

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

C
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 sure sa_flags and any extra fields start clean. Then call sigemptyset(&sa.sa_mask).
  • Keep handlers tiny. Set a volatile sig_atomic_t flag and return; do the real work in the main loop. Only async-signal-safe functions may be called from a handler: write, _exit, signal, sigaction and a short list of others. printf, malloc and free are not safe.
  • Save and restore errno in a handler that calls anything that may change it.
  • SA_RESTART makes read, write, accept and similar calls resume after a handler, instead of failing with EINTR. Without it, loops around such calls must handle EINTR.
  • 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 use sigsuspend, 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 use pthread_sigmask.
  • signal() differences. Under -std=c23 with glibc, signal() has one-shot semantics, while sigaction behaves the same everywhere.
  • Windows has only the ISO signal(); sigaction is POSIX.