sigreturn(2)

💖 sigreturn(2) — the "return from signal handler and cleanup stack frame" page 💖

okay bestie, gather round, because today we're reading sigreturn and its lil sibling rt_sigreturn from the System Calls Manual section 2. yes i know the title line normally says sigreturn(2) up top but we're doing it cute, stay with me. this is the internals of how signal handlers actually get back home, and honestly it's giving backstage-pass energy. 🎀

---

✨ LIBRARY ✨

Standard C library (libc, -lc) 🫶

---

✨ SYNOPSIS ✨

int sigreturn(...);

like... yes, the ... is real, and no, don't get any ideas, we'll get to that. 🙈

---

✨ DESCRIPTION ✨

okay so picture this. the Linux kernel is out here vibe-checking your process, and it notices an unblocked signal is pending. at the very next transition back to user mode in that process — think "upon return from a system call" or "when the process is rescheduled onto the CPU" — it does a little construction project on your user-space stack. it creates a new frame there and saves a whole lil scrapbook of process context: the processor status word, the registers, the signal mask, and the signal stack settings. ✨

the kernel also arranges that, during the transition back to user mode, the signal handler gets called. and then — this is the part — upon return from the handler, control passes to a piece of user-space code that everybody calls the "signal trampoline". the signal trampoline code then calls sigreturn(). 🩷

and this sigreturn() call undoes literally everything that was done in order to invoke the signal handler — the changing of the process's signal mask, the switching of signal stacks (see sigaltstack(2)), all of it. using the information that was earlier saved on the user-space stack, sigreturn() restores the process's signal mask, switches stacks, and restores the process's context (processor flags and registers, including the stack pointer and the instruction pointer), so that the process resumes execution at the exact point where it was interrupted by the signal. it's giving "we were never here" and i'm obsessed. 💅

---

✨ RETURN VALUE ✨

sigreturn() never returns. that's it. that's the whole section. main character behaviour tbh. 👑

---

✨ VERSIONS ✨

Many UNIX-type systems have a sigreturn() system call or something near equivalent. however, this call is not specified in POSIX, and the details of its behavior vary across systems. so, like, don't assume your friend's OS does what your OS does. ngl. 🌈

---

✨ STANDARDS ✨

None. 💀

---

✨ NOTES ✨

sigreturn() exists only to allow the implementation of signal handlers. It should never be called directly. (Indeed, a simple sigreturn() wrapper in the GNU C library simply returns -1, with errno set to ENOSYS.) like, do not. i am begging. 😭

Details of the arguments (if any) passed to sigreturn() vary depending on the architecture. (On some architectures, such as x86-64, sigreturn() takes no arguments, since all of the information that it requires is available in the stack frame that was previously created by the kernel on the user-space stack.) so that (...) in the synopsis is architecture-dependent chaos and we respect it for that. 🦋

Once upon a time, UNIX systems placed the signal trampoline code onto the user stack. Nowadays, pages of the user stack are protected so as to disallow code execution. thus, on contemporary Linux systems, depending on the architecture, the signal trampoline code lives either in the vdso(7) or in the C library. in the latter case, the C library's sigaction(2) wrapper function informs the kernel of the location of the trampoline code by placing its address in the sa_restorer field of the sigaction structure, and sets the SA_RESTORER flag in the sa_flags field. rental address, but for trampolines. 🏠✨

The saved process context information is placed in a ucontext_t structure (see <sys/ucontext.h>). That structure is visible within the signal handler as the third argument of a handler established via sigaction(2) with the SA_SIGINFO flag. so if you've ever wondered where that third arg came from: here. you're welcome. 💖

On some other UNIX systems, the operation of the signal trampoline differs a little. In particular, on some systems, upon transitioning back to user mode, the kernel passes control to the trampoline (rather than the signal handler), and the trampoline code calls the signal handler (and then calls sigreturn() once the handler returns). different route, same destination, slay. 🎀

🧚 C library/kernel differences 🧚

The original Linux system call was named sigreturn(). However, with the addition of real-time signals in Linux 2.2, a new system call, rt_sigreturn(), was added to support an enlarged sigset_t type. The GNU C library hides these details from us, transparently employing rt_sigreturn() when the kernel provides it. libc out here doing the emotional labour so we don't have to. 🫶

---

✨ SEE ALSO ✨

• kill(2)
• restart_syscall(2)
• sigaltstack(2)
• signal(2)
• getcontext(3)
• signal(7)
• vdso(7)

---

and that's the whole page bestie, no cap. this one came to you courtesy of Linux man-pages 6.20, dated 2026-02-08, filed under sigreturn(2). go forth and never call it directly. mwah 💋✨