| 1 |
.\" Copyright 2008-2014, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH sigreturn 2 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B int sigreturn(...); |
| 15 |
.fi |
| 16 |
.SH DESCRIPTION |
| 17 |
If the Linux kernel determines that an unblocked |
| 18 |
signal is pending for a process, then, |
| 19 |
at the next transition back to user mode in that process |
| 20 |
(e.g., upon return from a system call or |
| 21 |
when the process is rescheduled onto the CPU), |
| 22 |
it creates a new frame on the user-space stack where it |
| 23 |
saves various pieces of process context |
| 24 |
(processor status word, registers, signal mask, and signal stack settings). |
| 25 |
.\" See arch/x86/kernel/signal.c::__setup_frame() [in Linux 3.17 source code] |
| 26 |
.P |
| 27 |
The kernel also arranges that, during the transition back to user mode, |
| 28 |
the signal handler is called, and that, upon return from the handler, |
| 29 |
control passes to a piece of user-space code commonly called |
| 30 |
the "signal trampoline". |
| 31 |
The signal trampoline code in turn calls |
| 32 |
.BR sigreturn (). |
| 33 |
.P |
| 34 |
This |
| 35 |
.BR sigreturn () |
| 36 |
call undoes everything that was |
| 37 |
done\[em]changing the process's signal mask, switching signal stacks (see |
| 38 |
.BR sigaltstack "(2))\[em]in" |
| 39 |
order to invoke the signal handler. |
| 40 |
Using the information that was earlier saved on the user-space stack |
| 41 |
.BR sigreturn () |
| 42 |
restores the process's signal mask, switches stacks, |
| 43 |
and restores the process's context |
| 44 |
(processor flags and registers, |
| 45 |
including the stack pointer and instruction pointer), |
| 46 |
so that the process resumes execution |
| 47 |
at the point where it was interrupted by the signal. |
| 48 |
.SH RETURN VALUE |
| 49 |
.BR sigreturn () |
| 50 |
never returns. |
| 51 |
.SH VERSIONS |
| 52 |
Many UNIX-type systems have a |
| 53 |
.BR sigreturn () |
| 54 |
system call or near equivalent. |
| 55 |
However, this call is not specified in POSIX, |
| 56 |
and details of its behavior vary across systems. |
| 57 |
.SH STANDARDS |
| 58 |
None. |
| 59 |
.SH NOTES |
| 60 |
.BR sigreturn () |
| 61 |
exists only to allow the implementation of signal handlers. |
| 62 |
It should |
| 63 |
.B never |
| 64 |
be called directly. |
| 65 |
(Indeed, a simple |
| 66 |
.BR sigreturn () |
| 67 |
.\" See sysdeps/unix/sysv/linux/sigreturn.c and |
| 68 |
.\" signal/sigreturn.c in the glibc source |
| 69 |
wrapper in the GNU C library simply returns \-1, with |
| 70 |
.I errno |
| 71 |
set to |
| 72 |
.BR ENOSYS .) |
| 73 |
Details of the arguments (if any) passed to |
| 74 |
.BR sigreturn () |
| 75 |
vary depending on the architecture. |
| 76 |
(On some architectures, such as x86-64, |
| 77 |
.BR sigreturn () |
| 78 |
takes no arguments, since all of the information that it requires |
| 79 |
is available in the stack frame that was previously created by the |
| 80 |
kernel on the user-space stack.) |
| 81 |
.P |
| 82 |
Once upon a time, UNIX systems placed the signal trampoline code |
| 83 |
onto the user stack. |
| 84 |
Nowadays, pages of the user stack are protected so as to |
| 85 |
disallow code execution. |
| 86 |
Thus, on contemporary Linux systems, depending on the architecture, |
| 87 |
the signal trampoline code lives either in the |
| 88 |
.BR vdso (7) |
| 89 |
or in the C library. |
| 90 |
In the latter case, |
| 91 |
.\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and |
| 92 |
.\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source. |
| 93 |
the C library's |
| 94 |
.BR sigaction (2) |
| 95 |
wrapper function informs the kernel of the location of the trampoline code |
| 96 |
by placing its address in the |
| 97 |
.I sa_restorer |
| 98 |
field of the |
| 99 |
.I sigaction |
| 100 |
structure, |
| 101 |
and sets the |
| 102 |
.B SA_RESTORER |
| 103 |
flag in the |
| 104 |
.I sa_flags |
| 105 |
field. |
| 106 |
.P |
| 107 |
The saved process context information is placed in a |
| 108 |
.I ucontext_t |
| 109 |
structure (see |
| 110 |
.IR <sys/ucontext.h> ). |
| 111 |
That structure is visible within the signal handler |
| 112 |
as the third argument of a handler established via |
| 113 |
.BR sigaction (2) |
| 114 |
with the |
| 115 |
.B SA_SIGINFO |
| 116 |
flag. |
| 117 |
.P |
| 118 |
On some other UNIX systems, |
| 119 |
the operation of the signal trampoline differs a little. |
| 120 |
In particular, on some systems, upon transitioning back to user mode, |
| 121 |
the kernel passes control to the trampoline (rather than the signal handler), |
| 122 |
and the trampoline code calls the signal handler (and then calls |
| 123 |
.BR sigreturn () |
| 124 |
once the handler returns). |
| 125 |
.\" |
| 126 |
.SS C library/kernel differences |
| 127 |
The original Linux system call was named |
| 128 |
.BR sigreturn (). |
| 129 |
However, with the addition of real-time signals in Linux 2.2, |
| 130 |
a new system call, |
| 131 |
.BR rt_sigreturn () |
| 132 |
was added to support an enlarged |
| 133 |
.I sigset_t |
| 134 |
type. |
| 135 |
The GNU C library |
| 136 |
hides these details from us, transparently employing |
| 137 |
.BR rt_sigreturn () |
| 138 |
when the kernel provides it. |
| 139 |
.\" |
| 140 |
.SH SEE ALSO |
| 141 |
.BR kill (2), |
| 142 |
.BR restart_syscall (2), |
| 143 |
.BR sigaltstack (2), |
| 144 |
.BR signal (2), |
| 145 |
.BR getcontext (3), |
| 146 |
.BR signal (7), |
| 147 |
.BR vdso (7) |