| .\" Copyright (C) 2008, 2014, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Created Sat Aug 21 1995 Thomas K. Dyas <tdyas@eden.rutgers.edu> |
| .\" Modified Tue Oct 22 22:09:03 1996 by Eric S. Raymond <esr@thyrsus.com> |
| .\" 2008-06-26, mtk, added some more detail on the work done by sigreturn() |
| .\" 2014-12-05, mtk, rewrote all of the rest of the original page |
| .\" |
| .TH SIGRETURN 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame |
| .SH SYNOPSIS |
| .BI "int sigreturn(...);" |
| .SH DESCRIPTION |
| If the Linux kernel determines that an unblocked |
| signal is pending for a process, then, |
| at the next transition back to user mode in that process |
| (e.g., upon return from a system call or |
| when the process is rescheduled onto the CPU), |
| it creates a new frame on the user-space stack where it |
| saves various pieces of process context |
| (processor status word, registers, signal mask, and signal stack settings). |
| .\" See arch/x86/kernel/signal.c::__setup_frame() [in 3.17 source code] |
| .PP |
| The kernel also arranges that, during the transition back to user mode, |
| the signal handler is called, and that, upon return from the handler, |
| control passes to a piece of user-space code commonly called |
| the "signal trampoline". |
| The signal trampoline code in turn calls |
| .BR sigreturn (). |
| .PP |
| This |
| .BR sigreturn () |
| call undoes everything that was |
| done\(emchanging the process's signal mask, switching signal stacks (see |
| .BR sigaltstack "(2))\(emin " |
| order to invoke the signal handler. |
| Using the information that was earlier saved on the user-space stack |
| .BR sigreturn () |
| restores the process's signal mask, switches stacks, |
| and restores the process's context |
| (processor flags and registers, |
| including the stack pointer and instruction pointer), |
| so that the process resumes execution |
| at the point where it was interrupted by the signal. |
| .SH RETURN VALUE |
| .BR sigreturn () |
| never returns. |
| .SH CONFORMING TO |
| Many UNIX-type systems have a |
| .BR sigreturn () |
| system call or near equivalent. |
| However, this call is not specified in POSIX, |
| and details of its behavior vary across systems. |
| .SH NOTES |
| .BR sigreturn () |
| exists only to allow the implementation of signal handlers. |
| It should |
| .B never |
| be called directly. |
| (Indeed, a simple |
| .BR sigreturn () |
| .\" See sysdeps/unix/sysv/linux/sigreturn.c and |
| .\" signal/sigreturn.c in the glibc source |
| wrapper in the GNU C library simply returns -1, with |
| .I errno |
| set to |
| .BR ENOSYS .) |
| Details of the arguments (if any) passed to |
| .BR sigreturn () |
| vary depending on the architecture. |
| (On some architectures, such as x86-64, |
| .BR 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.) |
| .PP |
| 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 |
| .BR vdso (7) |
| or in the C library. |
| In the latter case, |
| .\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and |
| .\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source. |
| the C library's |
| .BR sigaction (2) |
| wrapper function informs the kernel of the location of the trampoline code |
| by placing its address in the |
| .I sa_restorer |
| field of the |
| .I sigaction |
| structure, |
| and sets the |
| .BR SA_RESTORER |
| flag in the |
| .IR sa_flags |
| field. |
| .PP |
| The saved process context information is placed in a |
| .I ucontext_t |
| structure (see |
| .IR <sys/ucontext.h> ). |
| That structure is visible within the signal handler |
| as the third argument of a handler established via |
| .BR sigaction (2) |
| with the |
| .BR SA_SIGINFO |
| flag. |
| .PP |
| 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 |
| .BR sigreturn () |
| once the handler returns). |
| .\" |
| .SS C library/kernel differences |
| The original Linux system call was named |
| .BR sigreturn (). |
| However, with the addition of real-time signals in Linux 2.2, |
| a new system call, |
| .BR rt_sigreturn () |
| was added to support an enlarged |
| .IR sigset_t |
| type. |
| The GNU C library |
| hides these details from us, transparently employing |
| .BR rt_sigreturn () |
| when the kernel provides it. |
| .\" |
| .SH SEE ALSO |
| .BR kill (2), |
| .BR restart_syscall (2), |
| .BR sigaltstack (2), |
| .BR signal (2), |
| .BR getcontext (3), |
| .BR signal (7), |
| .BR vdso (7) |