1sigreturn(2) System Calls Manual sigreturn(2)
2
6 sigreturn, rt_sigreturn - return from signal handler and cleanup stack
7 frame
8
10 Standard C library (libc, -lc)
11
13 int sigreturn(...);
14
16 If the Linux kernel determines that an unblocked signal is pending for
17 a process, then, at the next transition back to user mode in that
18 process (e.g., upon return from a system call or when the process is
19 rescheduled onto the CPU), it creates a new frame on the user-space
20 stack where it saves various pieces of process context (processor sta‐
21 tus word, registers, signal mask, and signal stack settings).
22 The kernel also arranges that, during the transition back to user mode,
24 the signal handler is called, and that, upon return from the handler,
25 control passes to a piece of user-space code commonly called the "sig‐
26 nal trampoline". The signal trampoline code in turn calls sigreturn().
27 This sigreturn() call undoes everything that was done—changing the
29 process's signal mask, switching signal stacks (see sigaltstack(2))—in
30 order to invoke the signal handler. Using the information that was
31 earlier saved on the user-space stack sigreturn() restores the
32 process's signal mask, switches stacks, and restores the process's con‐
33 text (processor flags and registers, including the stack pointer and
34 instruction pointer), so that the process resumes execution at the
35 point where it was interrupted by the signal.
36
38 sigreturn() never returns.
39
41 Many UNIX-type systems have a sigreturn() system call or near equiva‐
42 lent. However, this call is not specified in POSIX, and details of its
43 behavior vary across systems.
44
46 None.
47
49 sigreturn() exists only to allow the implementation of signal handlers.
50 It should never be called directly. (Indeed, a simple sigreturn()
51 wrapper in the GNU C library simply returns -1, with errno set to
52 ENOSYS.) Details of the arguments (if any) passed to sigreturn() vary
53 depending on the architecture. (On some architectures, such as x86-64,
54 sigreturn() takes no arguments, since all of the information that it
55 requires is available in the stack frame that was previously created by
56 the kernel on the user-space stack.)
57 Once upon a time, UNIX systems placed the signal trampoline code onto
59 the user stack. Nowadays, pages of the user stack are protected so as
60 to disallow code execution. Thus, on contemporary Linux systems, de‐
61 pending on the architecture, the signal trampoline code lives either in
62 the vdso(7) or in the C library. In the latter case, the C library's
63 sigaction(2) wrapper function informs the kernel of the location of the
64 trampoline code by placing its address in the sa_restorer field of the
65 sigaction structure, and sets the SA_RESTORER flag in the sa_flags
66 field.
67 The saved process context information is placed in a ucontext_t struc‐
69 ture (see <sys/ucontext.h>). That structure is visible within the sig‐
70 nal handler as the third argument of a handler established via sigac‐
71 tion(2) with the SA_SIGINFO flag.
72 On some other UNIX systems, the operation of the signal trampoline dif‐
74 fers a little. In particular, on some systems, upon transitioning back
75 to user mode, the kernel passes control to the trampoline (rather than
76 the signal handler), and the trampoline code calls the signal handler
77 (and then calls sigreturn() once the handler returns).
78 C library/kernel differences
80 The original Linux system call was named sigreturn(). However, with
81 the addition of real-time signals in Linux 2.2, a new system call,
82 rt_sigreturn() was added to support an enlarged sigset_t type. The GNU
83 C library hides these details from us, transparently employing rt_si‐
84 greturn() when the kernel provides it.
85
87 kill(2), restart_syscall(2), sigaltstack(2), signal(2), getcontext(3),
88 signal(7), vdso(7)
89Linux man-pages 6.04 2023-03-30 sigreturn(2)