original/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 2014-12-31 "Linux" "Linux Programmer's Manual"
  31 .SH NAME
  32 sigreturn \- return from signal handler and cleanup stack frame
  33 .SH SYNOPSIS
  34 .BI "int sigreturn(...);"
  35 .SH DESCRIPTION
  36 If the Linux kernel determines that an unblocked
  37 signal is pending for a process, then,
  38 at the next transition back to user mode in that process
  39 (e.g., upon return from a system call or
  40 when the process is rescheduled onto the CPU),
  41 it saves various pieces of process context
  42 (processor status word, registers, signal mask, and signal stack settings)
  43 into the user-space stack.
  44 .\" See arch/x86/kernel/signal.c::__setup_frame() [in 3.17 source code]
  45
  46 The kernel also arranges that, during the transition back to user mode,
  47 the signal handler is called, and that, upon return from the handler,
  48 control passes to a piece of user-space code commonly called
  49 the "signal trampoline".
  50 The signal trampoline code in turn calls
  51 .BR sigreturn ().
  52
  53 This
  54 .BR sigreturn ()
  55 call undoes everything that was
  56 done\(emchanging the process's signal mask, switching signal stacks (see
  57 .BR sigaltstack "(2))\(emin "
  58 order to invoke the signal handler.
  59 It restores the process's signal mask, switches stacks,
  60 and restores the process's context
  61 (processor flags and registers,
  62 including the stack pointer and instruction pointer),
  63 so that the process resumes execution
  64 at the point where it was interrupted by the signal.
  65 .SH RETURN VALUE
  66 .BR sigreturn ()
  67 never returns.
  68 .SH CONFORMING TO
  69 Many UNIX-type systems have a
  70 .BR sigreturn ()
  71 system call or near equivalent.
  72 However, this call is not specified in POSIX,
  73 and details of its behavior vary across systems.
  74 .SH NOTES
  75 .BR sigreturn ()
  76 exists only to allow the implementation of signal handlers.
  77 It should
  78 .B never
  79 be called directly.
  80 Details of the arguments (if any) passed to
  81 .BR sigreturn ()
  82 vary depending on the architecture.
  83
  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 supplies the location of the trampoline code using the
  96 .I sa_restorer
  97 field of the
  98 .I sigaction
  99 structure that is passed to
 100 .BR sigaction (2),
 101 and sets the
 102 .BR SA_RESTORER
 103 flag in the
 104 .IR sa_flags
 105 field.
 106
 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 with the
 113 .BR SA_SIGINFO
 114 flag.
 115
 116 On some other UNIX systems,
 117 the operation of the signal trampoline differs a little.
 118 In particular, on some systems, upon transitioning back to user mode,
 119 the kernel passes control to the trampoline (rather than the signal handler),
 120 and the trampoline code calls the signal handler (and then calls
 121 .BR sigreturn ()
 122 once the handler returns).
 123 .SH SEE ALSO
 124 .BR kill (2),
 125 .BR restart_syscall (2),
 126 .BR sigaltstack (2),
 127 .BR signal (2),
 128 .BR getcontext (3),
 129 .BR signal (7)
 130 .SH COLOPHON
 131 This page is part of release 3.79 of the Linux
 132 .I man-pages
 133 project.
 134 A description of the project,
 135 information about reporting bugs,
 136 and the latest version of this page,
 137 can be found at
 138 \%http://www.kernel.org/doc/man\-pages/.