SIGHOLD(3POSIX)

💖 SIGHOLD(3POSIX) — the POSIX Programmer's Manual, but make it make sense 💖

okay bestie, welcome to SIGHOLD(3POSIX) from the POSIX Programmer's Manual ✨ this is the girlies' guide to the old-school signal management squad and yes, we're gonna get through all of it together, no cap 🫶

---

🌸 PROLOG 🌸

okay so real talk first, this is important:

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

so like… don't come for me if Linux does its own thing, that's literally what the page says 💀

---

✨ NAME ✨

sighold, sigignore, sigpause, sigrelse, sigset — signal management

it's giving "the whole girl group, five members, one job" 👑

---

🎀 SYNOPSIS 🎀

#include <signal.h>

int sighold(int sig);
int sigignore(int sig);
int sigpause(int sig);
int sigrelse(int sig);
void (*sigset(int sig, void (*disp)(int)))(int);

yes that last one is a function returning a function pointer, she's highkey iconic and also a little scary, we love her 💅

---

🦋 DESCRIPTION 🦋

okay first things first, the disclaimer:

Use of any of these functions is unspecified in a multi-threaded process.

so like, single-threaded girlies only for this whole crew, periodt 💀

The sighold(), sigignore(), sigpause(), sigrelse(), and sigset() functions provide simplified signal management. simplified! because sometimes you don't wanna do the whole big thing 🧚

sigset() — the main character 👑

The sigset() function shall modify signal dispositions.

• The sig argument specifies the signal, which may be any signal except SIGKILL and SIGSTOP.
• The disp argument specifies the signal's disposition, which may be SIG_DFL, SIG_IGN, or the address of a signal handler.

now here's the tea, three separate scenarios:

• If sigset() is used, and disp is the address of a signal handler, the system shall add sig to the signal mask of the calling process before executing the signal handler; when the signal handler returns, the system shall restore the signal mask of the calling process to its state prior to the delivery of the signal. so she blocks herself while she's handling business, very self-aware 💅
• In addition, if sigset() is used, and disp is equal to SIG_HOLD, sig shall be added to the signal mask of the calling process and sig's disposition shall remain unchanged.
• If sigset() is used, and disp is not equal to SIG_HOLD, sig shall be removed from the signal mask of the calling process.

the rest of the squad 🌈

• The sighold() function shall add sig to the signal mask of the calling process.
• The sigrelse() function shall remove sig from the signal mask of the calling process.
• The sigignore() function shall set the disposition of sig to SIG_IGN.
• The sigpause() function shall remove sig from the signal mask of the calling process and suspend the calling process until a signal is received. The sigpause() function shall restore the signal mask of the process to its original state before returning.

the SIGCHLD situation 😭

this one's a whole plot twist, pay attention:

If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the calling processes shall not be transformed into zombie processes when they terminate.

If the calling process subsequently waits for its children, and the process has no unwaited-for children that were transformed into zombie processes, it shall block until all of its children terminate, and wait(), waitid(), and waitpid() shall fail and set errno to [ECHILD].

no zombies but also no chill, the tradeoff is real 🙈

---

💜 RETURN VALUE 💜

okay so what do you get back:

• Upon successful completion, sigset() shall return SIG_HOLD if the signal had been blocked, and the signal's previous disposition if it had not been blocked. Otherwise, SIG_ERR shall be returned and errno set to indicate the error.
• The sigpause() function shall suspend execution of the thread until a signal is received, whereupon it shall return -1 and set errno to [EINTR].
• For all other functions, upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to indicate the error.

so: two functions with ✨personality✨ and the rest being basic 0/-1 girlies 🎀

---

🔥 ERRORS 🔥

These functions shall fail if:

• EINVAL — The sig argument is an illegal signal number.

The sigset() and sigignore() functions shall fail if:

• EINVAL — An attempt is made to catch a signal that cannot be caught, or to ignore a signal that cannot be ignored.

two different EINVAL flavors, same name, different drama 💀

The following sections are informative.

---

🌟 EXAMPLES 🌟

None.

literally none, the well is dry bestie, moving on 🫶

---

🌈 APPLICATION USAGE 🌈

• The sigaction() function provides a more comprehensive and reliable mechanism for controlling signals; new applications should use the sigaction() function instead of the obsolescent sigset() function.
• The sighold() function, in conjunction with sigrelse() or sigpause(), may be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred. For broader portability, the pthread_sigmask() or sigprocmask() functions should be used instead of the obsolescent sighold() and sigrelse() functions.
• For broader portability, the sigsuspend() function should be used instead of the obsolescent sigpause() function.

🚨 bestie listen: the word obsolescent is doing a lot of heavy lifting in this section. these are the legacy girlies. new code, new functions. periodt.

---

👑 RATIONALE 👑

Each of these historic functions has a direct analog in the other functions which are required to be per-thread and thread-safe (aside from sigprocmask(), which is replaced by pthread_sigmask()).

and here's the translation table, no cap:

• The sigset() function can be implemented as a simple wrapper for sigaction().
• The sighold() function is equivalent to sigprocmask() or pthread_sigmask() with SIG_BLOCK set.
• The sigignore() function is equivalent to sigaction() with SIG_IGN set.
• The sigpause() function is equivalent to sigsuspend().
• The sigrelse() function is equivalent to sigprocmask() or pthread_sigmask() with SIG_UNBLOCK set.

so basically the whole crew is a cover band for the modern functions, and honestly? respect 🎤

---

🦄 FUTURE DIRECTIONS 🦄

These functions may be removed in a future version.

💀 they said "may be removed" which is the manual-page equivalent of "we need to talk"

---

💅 SEE ALSO 💅

• Section 2.4, Signal Concepts
• exec
• pause()
• pthread_sigmask()
• sigaction()
• signal()
• sigsuspend()
• wait()
• waitid()
• The Base Definitions volume of POSIX.1‐2017, <signal.h>

go read those, they're the glow-up versions of everything above 🌸

---

🍓 COPYRIGHT 🍓

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 that's the whole page bestie, and a lil sign-off for you: this one came from IEEE/The Open Group, dated 2017, filed under SIGHOLD(3POSIX) 💖 you understood all of that and honestly? slay. go forth and block your signals responsibly 🫶✨🎀