sigreturn.2: Add (a lot) more detail on the signal trampoline

And rewrite much of the page.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/sigreturn.2

@@ -1,4 +1,4 @@
-.\" Copyright (C) 1995, Thomas K. Dyas <tdyas@eden.rutgers.edu>
+.\" Copyright (C) 2008, 2014, Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -25,51 +25,105 @@
 .\" Created   Sat Aug 21 1995     Thomas K. Dyas <tdyas@eden.rutgers.edu>
 .\" Modified Tue Oct 22 22:09:03 1996 by Eric S. Raymond <esr@thyrsus.com>
 .\" 2008-06-26, mtk, added some more detail on the work done by sigreturn()
+.\" 2014-12-05, mtk, rewrote all of the rest of the original page
 .\"
 .TH SIGRETURN 2 2013-07-30 "Linux" "Linux Programmer's Manual"
 .SH NAME
 sigreturn \- return from signal handler and cleanup stack frame
 .SH SYNOPSIS
-.BI "int sigreturn(unsigned long " __unused );
+.BI "int sigreturn(...);"
 .SH DESCRIPTION
-When the Linux kernel creates the stack frame for a signal handler, a
+If the Linux kernel determines that an unblocked
-call to
+signal is pending for a process, then,
-.BR sigreturn ()
+at the next transition back to user mode in that process
-is inserted into the stack frame so that upon
+(e.g., upon return from a system call or
-return from the signal handler,
+when the process is rescheduled onto the CPU),
-.BR sigreturn ()
+it saves various pieces of process context
-will be called.
+(processor status word, registers, signal mask, and signal stack settings)
+into the user-space stack.
+.\" See arch/x86/kernel/signal.c::__setup_frame() [in 3.17 source code]
+
+The kernel also arranges that, during the transition back to user mode,
+the signal handler is called, and that, upon return from the handler,
+control passes to a piece of user-space code commonly called
+the "signal trampoline".
+The signal trampoline code in turn calls
+.BR sigreturn ().
 
 This
 .BR sigreturn ()
 call undoes everything that was
-done\(emchanging the process's signal mask, switching stacks (see
+done\(emchanging the process's signal mask, switching signal stacks (see
 .BR sigaltstack "(2))\(emin "
-order to invoke the signal handler:
+order to invoke the signal handler.
-it restores the process's signal mask, switches stacks,
+It restores the process's signal mask, switches stacks,
-and restores the process's context (registers, processor flags),
+and restores the process's context
-so that the process directly resumes execution
+(processor flags and registers,
+including the stack pointer and instruction pointer),
+so that the process resumes execution
 at the point where it was interrupted by the signal.
 .SH RETURN VALUE
 .BR sigreturn ()
 never returns.
 .SH CONFORMING TO
+Many UNIX-type systems have a
 .BR sigreturn ()
-is specific to Linux and should not be used in programs intended to be
+system call or near equivalent.
-portable.
+However, this call is not specified in POSIX,
+and details of its behavior vary across systems.
 .SH NOTES
-The
 .BR sigreturn ()
-call is used by the kernel to implement signal handlers.
+exists only to allow the implementation of signal handlers.
 It should
 .B never
 be called directly.
-Better yet, the specific use of the
+Details of the arguments (if any) passed to
-.I __unused
+.BR sigreturn ()
-argument varies depending on the architecture.
+vary depending on the architecture.
+
+Once upon a time, UNIX systems placed the signal trampoline code
+onto the user stack.
+Nowadays, pages of the user stack are protected so as to
+disallow code execution.
+Thus, on contemporary Linux systems, depending on the architecture,
+the signal trampoline code lives either in the
+.BR vdso (7)
+or in the C library.
+In the latter case,
+.\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and
+.\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source.
+the C library supplies the location of the trampoline code using the
+.I sa_restorer
+field of the
+.I sigaction
+structure that is passed to
+.BR sigaction (2),
+and sets the
+.BR SA_RESTORER
+flag in the
+.IR sa_flags
+field.
+
+The saved process context information is placed in a
+.I ucontext_t
+structure (see
+.IR <sys/ucontext.h> ).
+That structure is visible within the signal handler
+as the third argument of a handler established with the
+.BR SA_SIGINFO
+flag.
+
+On some other UNIX systems,
+the operation of the signal trampoline differs a little.
+In particular, on some systems, upon transitioning back to user mode,
+the kernel passes control to the trampoline (rather than the signal handler),
+and the trampoline code calls the signal handler (and then calls
+.BR sigreturn ()
+once the handler returns).
 .SH SEE ALSO
 .BR kill (2),
 .BR restart_syscall (2),
 .BR sigaltstack (2),
 .BR signal (2),
+.BR getcontext (3),
 .BR signal (7)