man2/sigreturn.2

   1 .\" Copyright (C) 2008, 2014, Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Created   Sat Aug 21 1995     Thomas K. Dyas <tdyas@eden.rutgers.edu>
   6 .\" Modified Tue Oct 22 22:09:03 1996 by Eric S. Raymond <esr@thyrsus.com>
   7 .\" 2008-06-26, mtk, added some more detail on the work done by sigreturn()
   8 .\" 2014-12-05, mtk, rewrote all of the rest of the original page
   9 .\"
  10 .TH SIGRETURN 2 2022-09-09 "Linux man-pages (unreleased)"
  11 .SH NAME
  12 sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B int sigreturn(...);
  19 .fi
  20 .SH DESCRIPTION
  21 If the Linux kernel determines that an unblocked
  22 signal is pending for a process, then,
  23 at the next transition back to user mode in that process
  24 (e.g., upon return from a system call or
  25 when the process is rescheduled onto the CPU),
  26 it creates a new frame on the user-space stack where it
  27 saves various pieces of process context
  28 (processor status word, registers, signal mask, and signal stack settings).
  29 .\" See arch/x86/kernel/signal.c::__setup_frame() [in 3.17 source code]
  30 .PP
  31 The kernel also arranges that, during the transition back to user mode,
  32 the signal handler is called, and that, upon return from the handler,
  33 control passes to a piece of user-space code commonly called
  34 the "signal trampoline".
  35 The signal trampoline code in turn calls
  36 .BR sigreturn ().
  37 .PP
  38 This
  39 .BR sigreturn ()
  40 call undoes everything that was
  41 done\(emchanging the process's signal mask, switching signal stacks (see
  42 .BR sigaltstack "(2))\(emin"
  43 order to invoke the signal handler.
  44 Using the information that was earlier saved on the user-space stack
  45 .BR sigreturn ()
  46 restores the process's signal mask, switches stacks,
  47 and restores the process's context
  48 (processor flags and registers,
  49 including the stack pointer and instruction pointer),
  50 so that the process resumes execution
  51 at the point where it was interrupted by the signal.
  52 .SH RETURN VALUE
  53 .BR sigreturn ()
  54 never returns.
  55 .SH STANDARDS
  56 Many UNIX-type systems have a
  57 .BR sigreturn ()
  58 system call or near equivalent.
  59 However, this call is not specified in POSIX,
  60 and details of its behavior vary across systems.
  61 .SH NOTES
  62 .BR sigreturn ()
  63 exists only to allow the implementation of signal handlers.
  64 It should
  65 .B never
  66 be called directly.
  67 (Indeed, a simple
  68 .BR sigreturn ()
  69 .\" See sysdeps/unix/sysv/linux/sigreturn.c and
  70 .\" signal/sigreturn.c in the glibc source
  71 wrapper in the GNU C library simply returns \-1, with
  72 .I errno
  73 set to
  74 .BR ENOSYS .)
  75 Details of the arguments (if any) passed to
  76 .BR sigreturn ()
  77 vary depending on the architecture.
  78 (On some architectures, such as x86-64,
  79 .BR sigreturn ()
  80 takes no arguments, since all of the information that it requires
  81 is available in the stack frame that was previously created by the
  82 kernel on the user-space stack.)
  83 .PP
  84 Once upon a time, UNIX systems placed the signal trampoline code
  85 onto the user stack.
  86 Nowadays, pages of the user stack are protected so as to
  87 disallow code execution.
  88 Thus, on contemporary Linux systems, depending on the architecture,
  89 the signal trampoline code lives either in the
  90 .BR vdso (7)
  91 or in the C library.
  92 In the latter case,
  93 .\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and
  94 .\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source.
  95 the C library's
  96 .BR sigaction (2)
  97 wrapper function informs the kernel of the location of the trampoline code
  98 by placing its address in the
  99 .I sa_restorer
 100 field of the
 101 .I sigaction
 102 structure,
 103 and sets the
 104 .B SA_RESTORER
 105 flag in the
 106 .I sa_flags
 107 field.
 108 .PP
 109 The saved process context information is placed in a
 110 .I ucontext_t
 111 structure (see
 112 .IR <sys/ucontext.h> ).
 113 That structure is visible within the signal handler
 114 as the third argument of a handler established via
 115 .BR sigaction (2)
 116 with the
 117 .B SA_SIGINFO
 118 flag.
 119 .PP
 120 On some other UNIX systems,
 121 the operation of the signal trampoline differs a little.
 122 In particular, on some systems, upon transitioning back to user mode,
 123 the kernel passes control to the trampoline (rather than the signal handler),
 124 and the trampoline code calls the signal handler (and then calls
 125 .BR sigreturn ()
 126 once the handler returns).
 127 .\"
 128 .SS C library/kernel differences
 129 The original Linux system call was named
 130 .BR sigreturn ().
 131 However, with the addition of real-time signals in Linux 2.2,
 132 a new system call,
 133 .BR rt_sigreturn ()
 134 was added to support an enlarged
 135 .I sigset_t
 136 type.
 137 The GNU C library
 138 hides these details from us, transparently employing
 139 .BR rt_sigreturn ()
 140 when the kernel provides it.
 141 .\"
 142 .SH SEE ALSO
 143 .BR kill (2),
 144 .BR restart_syscall (2),
 145 .BR sigaltstack (2),
 146 .BR signal (2),
 147 .BR getcontext (3),
 148 .BR signal (7),
 149 .BR vdso (7)