Debian Codegraph @

upstream/debian-unstable/man2/sigreturn.2

raw
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)