1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
.\" Copyright (C) 2008, 2014, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" 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 (date) "Linux man-pages (unreleased)"
.SH NAME
sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B int sigreturn(...);
.fi
.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 Linux 3.17 source code]
.P
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 ().
.P
This
.BR sigreturn ()
call undoes everything that was
done\[em]changing the process's signal mask, switching signal stacks (see
.BR sigaltstack "(2))\[em]in"
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 VERSIONS
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 STANDARDS
None.
.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.)
.P
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
.B SA_RESTORER
flag in the
.I sa_flags
field.
.P
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
.B SA_SIGINFO
flag.
.P
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
.I 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)
|
