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 (date) "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 Linux 3.17 source code]
  30 .P
  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 .P
  38 This
  39 .BR sigreturn ()
  40 call undoes everything that was
  41 done\[em]changing the process's signal mask, switching signal stacks (see
  42 .BR sigaltstack "(2))\[em]in"
  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 VERSIONS
  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 STANDARDS
  62 None.
  63 .SH NOTES
  64 .BR sigreturn ()
  65 exists only to allow the implementation of signal handlers.
  66 It should
  67 .B never
  68 be called directly.
  69 (Indeed, a simple
  70 .BR sigreturn ()
  71 .\" See sysdeps/unix/sysv/linux/sigreturn.c and
  72 .\" signal/sigreturn.c in the glibc source
  73 wrapper in the GNU C library simply returns \-1, with
  74 .I errno
  75 set to
  76 .BR ENOSYS .)
  77 Details of the arguments (if any) passed to
  78 .BR sigreturn ()
  79 vary depending on the architecture.
  80 (On some architectures, such as x86-64,
  81 .BR sigreturn ()
  82 takes no arguments, since all of the information that it requires
  83 is available in the stack frame that was previously created by the
  84 kernel on the user-space stack.)
  85 .P
  86 Once upon a time, UNIX systems placed the signal trampoline code
  87 onto the user stack.
  88 Nowadays, pages of the user stack are protected so as to
  89 disallow code execution.
  90 Thus, on contemporary Linux systems, depending on the architecture,
  91 the signal trampoline code lives either in the
  92 .BR vdso (7)
  93 or in the C library.
  94 In the latter case,
  95 .\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and
  96 .\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source.
  97 the C library's
  98 .BR sigaction (2)
  99 wrapper function informs the kernel of the location of the trampoline code
 100 by placing its address in the
 101 .I sa_restorer
 102 field of the
 103 .I sigaction
 104 structure,
 105 and sets the
 106 .B SA_RESTORER
 107 flag in the
 108 .I sa_flags
 109 field.
 110 .P
 111 The saved process context information is placed in a
 112 .I ucontext_t
 113 structure (see
 114 .IR <sys/ucontext.h> ).
 115 That structure is visible within the signal handler
 116 as the third argument of a handler established via
 117 .BR sigaction (2)
 118 with the
 119 .B SA_SIGINFO
 120 flag.
 121 .P
 122 On some other UNIX systems,
 123 the operation of the signal trampoline differs a little.
 124 In particular, on some systems, upon transitioning back to user mode,
 125 the kernel passes control to the trampoline (rather than the signal handler),
 126 and the trampoline code calls the signal handler (and then calls
 127 .BR sigreturn ()
 128 once the handler returns).
 129 .\"
 130 .SS C library/kernel differences
 131 The original Linux system call was named
 132 .BR sigreturn ().
 133 However, with the addition of real-time signals in Linux 2.2,
 134 a new system call,
 135 .BR rt_sigreturn ()
 136 was added to support an enlarged
 137 .I sigset_t
 138 type.
 139 The GNU C library
 140 hides these details from us, transparently employing
 141 .BR rt_sigreturn ()
 142 when the kernel provides it.
 143 .\"
 144 .SH SEE ALSO
 145 .BR kill (2),
 146 .BR restart_syscall (2),
 147 .BR sigaltstack (2),
 148 .BR signal (2),
 149 .BR getcontext (3),
 150 .BR signal (7),
 151 .BR vdso (7)