]>
Commit | Line | Data |
---|---|---|
eda078d4 | 1 | .\" Copyright (C) 2008, 2014, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Created Sat Aug 21 1995 Thomas K. Dyas <tdyas@eden.rutgers.edu> | |
26 | .\" Modified Tue Oct 22 22:09:03 1996 by Eric S. Raymond <esr@thyrsus.com> | |
0678a1d4 | 27 | .\" 2008-06-26, mtk, added some more detail on the work done by sigreturn() |
eda078d4 | 28 | .\" 2014-12-05, mtk, rewrote all of the rest of the original page |
fea681da | 29 | .\" |
4b8c67d9 | 30 | .TH SIGRETURN 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 31 | .SH NAME |
d893db64 | 32 | sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame |
fea681da | 33 | .SH SYNOPSIS |
eda078d4 | 34 | .BI "int sigreturn(...);" |
fea681da | 35 | .SH DESCRIPTION |
eda078d4 MK |
36 | If the Linux kernel determines that an unblocked |
37 | signal is pending for a process, then, | |
38 | at the next transition back to user mode in that process | |
39 | (e.g., upon return from a system call or | |
40 | when the process is rescheduled onto the CPU), | |
dea3ec0c MK |
41 | it creates a new frame on the user-space stack where it |
42 | saves various pieces of process context | |
43 | (processor status word, registers, signal mask, and signal stack settings). | |
eda078d4 | 44 | .\" See arch/x86/kernel/signal.c::__setup_frame() [in 3.17 source code] |
efeece04 | 45 | .PP |
eda078d4 MK |
46 | The kernel also arranges that, during the transition back to user mode, |
47 | the signal handler is called, and that, upon return from the handler, | |
48 | control passes to a piece of user-space code commonly called | |
49 | the "signal trampoline". | |
50 | The signal trampoline code in turn calls | |
51 | .BR sigreturn (). | |
efeece04 | 52 | .PP |
00ac6ce4 | 53 | This |
e511ffb6 | 54 | .BR sigreturn () |
0678a1d4 | 55 | call undoes everything that was |
eda078d4 | 56 | done\(emchanging the process's signal mask, switching signal stacks (see |
0678a1d4 | 57 | .BR sigaltstack "(2))\(emin " |
eda078d4 | 58 | order to invoke the signal handler. |
dea3ec0c MK |
59 | Using the information that was earlier saved on the user-space stack |
60 | .BR sigreturn () | |
61 | restores the process's signal mask, switches stacks, | |
eda078d4 MK |
62 | and restores the process's context |
63 | (processor flags and registers, | |
64 | including the stack pointer and instruction pointer), | |
65 | so that the process resumes execution | |
0678a1d4 | 66 | at the point where it was interrupted by the signal. |
47297adb | 67 | .SH RETURN VALUE |
e511ffb6 | 68 | .BR sigreturn () |
fea681da | 69 | never returns. |
47297adb | 70 | .SH CONFORMING TO |
eda078d4 | 71 | Many UNIX-type systems have a |
2dd578fd | 72 | .BR sigreturn () |
eda078d4 MK |
73 | system call or near equivalent. |
74 | However, this call is not specified in POSIX, | |
75 | and details of its behavior vary across systems. | |
6c36ac81 | 76 | .SH NOTES |
e511ffb6 | 77 | .BR sigreturn () |
eda078d4 | 78 | exists only to allow the implementation of signal handlers. |
c13182ef | 79 | It should |
fea681da | 80 | .B never |
c13182ef | 81 | be called directly. |
d03e0ad3 MK |
82 | (Indeed, a simple |
83 | .BR sigreturn () | |
84 | .\" See sysdeps/unix/sysv/linux/sigreturn.c and | |
85 | .\" signal/sigreturn.c in the glibc source | |
86 | wrapper in the GNU C library simply returns -1, with | |
87 | .I errno | |
88 | set to | |
89 | .BR ENOSYS .) | |
eda078d4 MK |
90 | Details of the arguments (if any) passed to |
91 | .BR sigreturn () | |
92 | vary depending on the architecture. | |
dea3ec0c MK |
93 | (On some architectures, such as x86-64, |
94 | .BR sigreturn () | |
95 | takes no arguments, since all of the information that it requires | |
96 | is available in the stack frame that was previously created by the | |
97 | kernel on the user-space stack.) | |
efeece04 | 98 | .PP |
eda078d4 MK |
99 | Once upon a time, UNIX systems placed the signal trampoline code |
100 | onto the user stack. | |
101 | Nowadays, pages of the user stack are protected so as to | |
102 | disallow code execution. | |
103 | Thus, on contemporary Linux systems, depending on the architecture, | |
104 | the signal trampoline code lives either in the | |
105 | .BR vdso (7) | |
106 | or in the C library. | |
107 | In the latter case, | |
108 | .\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and | |
109 | .\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source. | |
89559e3c MK |
110 | the C library's |
111 | .BR sigaction (2) | |
112 | wrapper function informs the kernel of the location of the trampoline code | |
113 | by placing its address in the | |
eda078d4 MK |
114 | .I sa_restorer |
115 | field of the | |
116 | .I sigaction | |
89559e3c | 117 | structure, |
eda078d4 MK |
118 | and sets the |
119 | .BR SA_RESTORER | |
120 | flag in the | |
121 | .IR sa_flags | |
122 | field. | |
efeece04 | 123 | .PP |
eda078d4 MK |
124 | The saved process context information is placed in a |
125 | .I ucontext_t | |
126 | structure (see | |
127 | .IR <sys/ucontext.h> ). | |
128 | That structure is visible within the signal handler | |
cc158fa3 MK |
129 | as the third argument of a handler established via |
130 | .BR sigaction (2) | |
131 | with the | |
eda078d4 MK |
132 | .BR SA_SIGINFO |
133 | flag. | |
efeece04 | 134 | .PP |
eda078d4 MK |
135 | On some other UNIX systems, |
136 | the operation of the signal trampoline differs a little. | |
137 | In particular, on some systems, upon transitioning back to user mode, | |
138 | the kernel passes control to the trampoline (rather than the signal handler), | |
139 | and the trampoline code calls the signal handler (and then calls | |
140 | .BR sigreturn () | |
141 | once the handler returns). | |
d893db64 | 142 | .\" |
0722a578 | 143 | .SS C library/kernel differences |
d893db64 MK |
144 | The original Linux system call was named |
145 | .BR sigreturn (). | |
146 | However, with the addition of real-time signals in Linux 2.2, | |
147 | a new system call, | |
148 | .BR rt_sigreturn () | |
149 | was added to support an enlarged | |
150 | .IR sigset_t | |
151 | type. | |
152 | The GNU C library | |
153 | hides these details from us, transparently employing | |
154 | .BR rt_sigreturn () | |
155 | when the kernel provides it. | |
156 | .\" | |
47297adb | 157 | .SH SEE ALSO |
fea681da | 158 | .BR kill (2), |
d806bc05 | 159 | .BR restart_syscall (2), |
e91751c9 | 160 | .BR sigaltstack (2), |
fea681da | 161 | .BR signal (2), |
eda078d4 | 162 | .BR getcontext (3), |
cc158601 MK |
163 | .BR signal (7), |
164 | .BR vdso (7) |