SIGACTION(3POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 SIGACTION(3POSIX) 💖

POSIX Programmer's Manual ✨ (yes bestie, this is the POSIX one, not the Linux one, keep reading)

🌸 PROLOG 🌸

okay so real talk before we get into it: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (so like, consult the corresponding Linux manual page for the deets on Linux behavior), or honestly the interface may not be implemented on Linux at all. 💀

👑 NAME 👑

sigaction — examine and change a signal action

🦋 SYNOPSIS 🦋

#include <signal.h>

int sigaction(int sig, const struct sigaction *restrict act,
    struct sigaction *restrict oact);

✨ DESCRIPTION ✨

so the sigaction() function lets the calling process examine and/or specify the action associated with a specific signal. The argument sig specifies the signal; the acceptable values are defined in <signal.h>. slay.

The structure sigaction, which is what you use to describe an action to be taken, is defined in the <signal.h> header to include at least the following members:

  • void (*)(int) — sa_handler — pointer to a signal-catching function, or one of the macros SIG_IGN or SIG_DFL.
  • sigset_t — sa_mask — an additional set of signals to be blocked during execution of the signal-catching function.
  • int — sa_flags — special flags to affect behavior of the signal.
  • void (*)(int, siginfo_t *, void *) — sa_sigaction — pointer to a signal-catching function.
🚨 important: the storage occupied by sa_handler and sa_sigaction may overlap, and a conforming application shall not use both simultaneously. pick a lane bestie.

If the argument act is not a null pointer, it points to a structure specifying the action to be associated with the specified signal. If the argument oact is not a null pointer, the action previously associated with the signal is stored in the location pointed to by the argument oact. And if the argument act is a null pointer, signal handling is unchanged — so you can use that call to just enquire about the current handling of a given signal. 🕵️‍♀️

The SIGKILL and SIGSTOP signals shall not be added to the signal mask using this mechanism; this restriction shall be enforced by the system without causing an error to be indicated. (the system just silently handles it, iconic behavior honestly.)

If the SA_SIGINFO flag (see below, bestie, it's right there) is cleared in the sa_flags field of the sigaction structure, the sa_handler field identifies the action to be associated with the specified signal. If the SA_SIGINFO flag is set in the sa_flags field, the sa_sigaction field specifies a signal-catching function.

The sa_flags field can be used to modify the behavior of the specified signal.

The following flags, defined in the <signal.h> header, can be set in sa_flags:

  • SA_NOCLDSTOP — do not generate SIGCHLD when children stop or stopped children continue.

If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, and the implementation supports the SIGCHLD signal, then a SIGCHLD signal shall be generated for the calling process whenever any of its child processes stop, and a SIGCHLD signal may be generated for the calling process whenever any of its stopped child processes are continued. If sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, then the implementation shall not generate a SIGCHLD signal in this way.

  • SA_ONSTACK — if set and an alternate signal stack has been declared with sigaltstack(), the signal shall be delivered to the calling process on that stack. Otherwise, the signal shall be delivered on the current stack.
  • SA_RESETHAND — if set, the disposition of the signal shall be reset to SIG_DFL and the SA_SIGINFO flag shall be cleared on entry to the signal handler.
📌 Note: SIGILL and SIGTRAP cannot be automatically reset when delivered; the system silently enforces this restriction.

Otherwise, the disposition of the signal shall not be modified on entry to the signal handler.

In addition, if this flag is set, sigaction() may behave as if the SA_NODEFER flag were also set. (sneaky!! 🙈)

  • SA_RESTART — this flag affects the behavior of interruptible functions; that is, those specified to fail with errno set to [EINTR]. If set, and a function specified as interruptible is interrupted by this signal, the function shall restart and shall not fail with [EINTR] unless otherwise specified. If an interruptible function which uses a timeout is restarted, the duration of the timeout following the restart is set to an unspecified value that does not exceed the original timeout value. If the flag is not set, interruptible functions interrupted by this signal shall fail with errno set to [EINTR].
  • SA_SIGINFO — if cleared and the signal is caught, the signal-catching function shall be entered as:
void func(int signo);

where signo is the only argument to the signal-catching function. In this case, the application shall use the sa_handler member to describe the signal-catching function, and the application shall not modify the sa_sigaction member.

If SA_SIGINFO is set and the signal is caught, the signal-catching function shall be entered as:

void func(int signo, siginfo_t *info, void *context);

where two additional arguments are passed to the signal-catching function. The second argument shall point to an object of type siginfo_t explaining the reason why the signal was generated; the third argument can be cast to a pointer to an object of type ucontext_t to refer to the receiving thread's context that was interrupted when the signal was delivered. In this case, the application shall use the sa_sigaction member to describe the signal-catching function, and the application shall not modify the sa_handler member.

The si_signo member contains the system-generated signal number. 🔢

The si_errno member may contain implementation-defined additional error information; if non-zero, it contains an error number identifying the condition that caused the signal to be generated.

The si_code member contains a code identifying the cause of the signal, as described in Section 2.4.3, Signal Actions.

  • SA_NOCLDWAIT — if sig does not equal SIGCHLD, the behavior is unspecified. Otherwise, the behavior of the SA_NOCLDWAIT flag is as specified in Consequences of Process Termination.
  • SA_NODEFER — if set and sig is caught, sig shall not be added to the thread's signal mask on entry to the signal handler unless it is included in sa_mask. Otherwise, sig shall always be added to the thread's signal mask on entry to the signal handler.

When a signal is caught by a signal-catching function installed by sigaction(), a new signal mask is calculated and installed for the duration of the signal-catching function (or until a call to either sigprocmask() or sigsuspend() is made). This mask is formed by taking the union of the current signal mask and the value of the sa_mask for the signal being delivered, and — unless SA_NODEFER or SA_RESETHAND is set — then including the signal being delivered. If and when the user's signal handler returns normally, the original signal mask is restored. ✨

Once an action is installed for a specific signal, it shall remain installed until another action is explicitly requested (by another call to sigaction()), until the SA_RESETHAND flag causes resetting of the handler, or until one of the exec functions is called.

If the previous action for sig had been established by signal(), the values of the fields returned in the structure pointed to by oact are unspecified, and in particular oact->sa_handler is not necessarily the same value passed to signal(). However, if a pointer to the same structure or a copy thereof is passed to a subsequent call to sigaction() via the act argument, handling of the signal shall be as if the original call to signal() were repeated. (okay so that's the trick, noted 📝)

If sigaction() fails, no new signal handler is installed. good to know fr fr.

It is unspecified whether an attempt to set the action for a signal that cannot be caught or ignored to SIG_DFL is ignored or causes an error to be returned with errno set to [EINVAL].

If SA_SIGINFO is not set in sa_flags, then the disposition of subsequent occurrences of sig when it is already pending is implementation-defined; the signal-catching function shall be invoked with a single argument. If SA_SIGINFO is set in sa_flags, then subsequent occurrences of sig generated by sigqueue() or as a result of any signal-generating function that supports the specification of an application-defined value (when sig is already pending) shall be queued in FIFO order until delivered or accepted; the signal-catching function shall be invoked with three arguments. The application specified value is passed to the signal-catching function as the si_value member of the siginfo_t structure.

The result of the use of sigaction() and a sigwait() function concurrently within a process on the same signal is unspecified. 🙈

💖 RETURN VALUE 💖

okay so when everything goes right, sigaction() returns 0. slay. but if it does NOT go right? it returns -1, and errno gets set to tell you what went wrong, and here's the important part bestie — no new signal-catching function shall be installed. like, nothing changes. the old handler stays. periodt.

😭 ERRORS 😭

so sigaction() shall fail if:

  • EINVAL — the sig argument is not a valid signal number, OR you're out here trying to catch a signal that literally cannot be caught, or ignore one that cannot be ignored. you cannot do that bestie, it's not gonna work.

and sigaction() may fail if:

  • EINVAL — an attempt was made to set the action to SIG_DFL for a signal that cannot be caught or ignored (or both). 💀

plus, on systems that do not support the XSI option, sigaction() may fail if the SA_SIGINFO flag is set in the sa_flags field of the sigaction structure for a signal that's not in the range SIGRTMIN to SIGRTMAX.

heads up: the next sections are the informative ones, so they're vibe-checks and advice, not hard requirements.

✨ EXAMPLES ✨

🎀 Establishing a Signal Handler

okay so here's how you use sigaction() to set up a handler for the SIGINT signal. it's giving classic, it's giving iconic:

#include <signal.h>

static void handler(int signum)
{
    /* Take appropriate actions for signal delivery */
}

int main()
{
    struct sigaction sa;

    sa.sa_handler = handler;
    sigemptyset(&sa.sa_mask);
    sa.sa_flags = SA_RESTART; /* Restart functions if
                                 interrupted by handler */
    if (sigaction(SIGINT, &sa, NULL) == -1)
        /* Handle error */;

    /* Further code */
}

see how we fill in sa.sa_handler, empty out the mask with sigemptyset(), set sa.sa_flags to SA_RESTART so interrupted functions get restarted, and then call sigaction(SIGINT, &sa, NULL)? and if it returns -1 you handle the error. that's it. that's the whole vibe. 💅

🌸 APPLICATION USAGE 🌸

sigaction() supersedes the signal() function, so bestie, use it in preference. and listen — sigaction() and signal() should not be used in the same process to control the same signal. do not do that. it's messy and we don't do messy.

now about async-signal-safe functions: the behavior of async-signal-safe functions, as defined in their respective DESCRIPTION sections, is as specified by this volume of POSIX.1‐2017, regardless of invocation from a signal-catching function. that's the only intended meaning of the statement that async-signal-safe functions may be used in signal-catching functions without restrictions. iykyk. applications must still consider all effects of such functions on things like data structures, files, and process state. in particular, app developers need to think about the restrictions on interactions when interrupting sleep() and interactions among multiple handles for a file description. and just because a function is listed as async-signal-safe does not necessarily mean invoking it from a signal-catching function is recommended. listed ≠ recommended, got it?

to prevent errors from interrupting non-async-signal-safe function calls, applications should protect calls to these functions either by blocking the appropriate signals or through the use of some programmatic semaphore (see semget(), sem_init(), sem_open(), and so on). and note — in particular — that even the ``safe'' functions may modify errno. so the signal-catching function, if it's not executing as an independent thread, should save and restore errno's value to avoid the possibility that delivery of a signal in between an error return from a function that sets errno and the subsequent examination of errno could result in the signal-catching function changing the value of errno. 😭 naturally, the same principles apply to the async-signal-safety of application routines and asynchronous data access.

also, longjmp() and siglongjmp() are not in the list of async-signal-safe functions. why? because the code executing after longjmp() and siglongjmp() can call any unsafe functions with the same danger as calling those unsafe functions directly from the signal handler. applications that use longjmp() and siglongjmp() from within signal handlers require rigorous protection in order to be portable. many of the other excluded functions are traditionally implemented using either malloc() or free() functions or the standard I/O library, both of which traditionally use data structures in a non-async-signal-safe manner. and since any combination of different functions using a common data structure can cause async-signal-safety problems, this volume of POSIX.1‐2017 does not define the behavior when any unsafe function is called in a signal handler that interrupts an unsafe function. undefined behavior alert, bestie, tread carefully.

usually, the signal is executed on the stack that was in effect before the signal was delivered. an alternate stack may be specified to receive a subset of the signals being caught. 🦋

when the signal handler returns, the receiving thread resumes execution at the point it was interrupted — unless the signal handler makes other arrangements. if longjmp() or _longjmp() is used to leave the signal handler, then the signal mask must be explicitly restored. don't forget, or it's over for you.

this volume of POSIX.1‐2017 defines the third argument of a signal handling function when SA_SIGINFO is set as a void * instead of a ucontext_t *, but without requiring type checking. new applications should explicitly cast the third argument of the signal handling function to ucontext_t *. do it, it's cleaner. ✨

the BSD optional four argument signal handling function is not supported by this volume of POSIX.1‐2017. the BSD declaration would be:

void handler(int sig, int code, struct sigcontext *scp,
    char *addr);

where sig is the signal number, code is additional information on certain signals, scp is a pointer to the sigcontext structure, and addr is additional address information. much the same information is available in the objects pointed to by the second argument of the signal handler specified when SA_SIGINFO is set.

since sigaction() is allowed but not required to set SA_NODEFER when the application sets the SA_RESETHAND flag, applications which depend on the SA_RESETHAND functionality for the newly installed signal handler must always explicitly set SA_NODEFER when they set SA_RESETHAND in order to be portable. both or it's not portable, no cap.

see also the rationale for Realtime Signal Generation and Delivery in the Rationale (Informative) volume of POSIX.1‐2017, Section B.2.4.2, Signal Generation and Delivery.

👑 RATIONALE 👑

so even though this volume of POSIX.1‐2017 requires that signals that cannot be ignored shall not be added to the signal mask when a signal-catching function is entered, there's no explicit requirement that subsequent calls to sigaction() reflect this in the information returned in the oact argument. in other words: if SIGKILL is included in the sa_mask field of act, it is unspecified whether or not a subsequent call to sigaction() returns with SIGKILL included in the sa_mask field of oact. 🙈 unspecified = don't rely on it.

the SA_NOCLDSTOP flag, when supplied in the act->sa_flags parameter, allows overloading SIGCHLD with the System V semantics that each SIGCLD signal indicates a single terminated child. most conforming applications that catch SIGCHLD are expected to install signal-catching functions that repeatedly call the waitpid() function with the WNOHANG flag set, acting on each child for which status is returned, until waitpid() returns zero. and if stopped children are not of interest, using the SA_NOCLDSTOP flag can prevent the overhead from invoking the signal-catching routine when they stop. efficiency, we love to see it.

some historical implementations also define other mechanisms for stopping processes, such as the ptrace() function. these implementations usually do not generate a SIGCHLD signal when processes stop due to this mechanism; however, that is beyond the scope of this volume of POSIX.1‐2017.

this volume of POSIX.1‐2017 requires that calls to sigaction() that supply a NULL act argument succeed, even in the case of signals that cannot be caught or ignored (that is, SIGKILL or SIGSTOP). the System V signal() and BSD sigvec() functions return [EINVAL] in these cases and, in this respect, their behavior varies from sigaction().

this volume of POSIX.1‐2017 requires that sigaction() properly save and restore a signal action set up by the ISO C standard signal() function. however, there's no guarantee that the reverse is true, nor could there be given the greater amount of information conveyed by the sigaction structure. because of this, applications should avoid using both functions for the same signal in the same process. since this cannot always be avoided in case of general-purpose library routines, they should always be implemented with sigaction(). 💅

it was intended that the signal() function should be implementable as a library routine using sigaction().

the POSIX Realtime Extension extends the sigaction() function as specified by the POSIX.1‐1990 standard to allow the application to request on a per-signal basis — via an additional signal action flag — that the extra parameters, including the application-defined signal value, if any, be passed to the signal-catching function.

🔮 FUTURE DIRECTIONS 🔮

None.

like literally none. nothing's changing here. stable as ever.

🌈 SEE ALSO 🌈

  • Section 2.4, Signal Concepts
  • exec
  • _Exit()
  • kill()
  • _longjmp()
  • longjmp()
  • pthread_sigmask()
  • raise()
  • semget()
  • sem_init()
  • sem_open()
  • sigaddset()
  • sigaltstack()
  • sigdelset()
  • sigemptyset()
  • sigfillset()
  • sigismember()
  • signal()
  • sigsuspend()
  • wait()
  • waitid()

and from the Base Definitions volume of POSIX.1‐2017: <signal.h> 🫶

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. the original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

okay bestie that's the whole page, we did it 💖 this one's from IEEE/The Open Group, dated 2017, and it's SIGACTION(3POSIX) — go forth and install those handlers responsibly, mwah 🎀✨

📦 where this page comes from