man2/sigreturn.2

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