1 files changed, 151 insertions, 0 deletions
diff --git a/man/man2/sigreturn.2 b/man/man2/sigreturn.2
new file mode 100644
index 000000000..1a34ef54c
--- /dev/null
+++ b/man/man2/sigreturn.2
@@ -0,0 +1,151 @@
+.\" Copyright (C) 2008, 2014, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 (date) "Linux man-pages (unreleased)"
+.SH NAME
+sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B int sigreturn(...);
+.fi
+.SH DESCRIPTION
+If the Linux kernel determines that an unblocked
+signal is pending for a process, then,
+at the next transition back to user mode in that process
+(e.g., upon return from a system call or
+when the process is rescheduled onto the CPU),
+it creates a new frame on the user-space stack where it
+saves various pieces of process context
+(processor status word, registers, signal mask, and signal stack settings).
+.\" See arch/x86/kernel/signal.c::__setup_frame() [in Linux 3.17 source code]
+.P
+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 ().
+.P
+This
+.BR sigreturn ()
+call undoes everything that was
+done\[em]changing the process's signal mask, switching signal stacks (see
+.BR sigaltstack "(2))\[em]in"
+order to invoke the signal handler.
+Using the information that was earlier saved on the user-space stack
+.BR sigreturn ()
+restores the process's signal mask, switches stacks,
+and restores the process's context
+(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 VERSIONS
+Many UNIX-type systems have a
+.BR sigreturn ()
+system call or near equivalent.
+However, this call is not specified in POSIX,
+and details of its behavior vary across systems.
+.SH STANDARDS
+None.
+.SH NOTES
+.BR sigreturn ()
+exists only to allow the implementation of signal handlers.
+It should
+.B never
+be called directly.
+(Indeed, a simple
+.BR sigreturn ()
+.\" See sysdeps/unix/sysv/linux/sigreturn.c and
+.\" signal/sigreturn.c in the glibc source
+wrapper in the GNU C library simply returns \-1, with
+.I errno
+set to
+.BR ENOSYS .)
+Details of the arguments (if any) passed to
+.BR sigreturn ()
+vary depending on the architecture.
+(On some architectures, such as x86-64,
+.BR sigreturn ()
+takes no arguments, since all of the information that it requires
+is available in the stack frame that was previously created by the
+kernel on the user-space stack.)
+.P
+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's
+.BR sigaction (2)
+wrapper function informs the kernel of the location of the trampoline code
+by placing its address in the
+.I sa_restorer
+field of the
+.I sigaction
+structure,
+and sets the
+.B SA_RESTORER
+flag in the
+.I sa_flags
+field.
+.P
+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 via
+.BR sigaction (2)
+with the
+.B SA_SIGINFO
+flag.
+.P
+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).
+.\"
+.SS C library/kernel differences
+The original Linux system call was named
+.BR sigreturn ().
+However, with the addition of real-time signals in Linux 2.2,
+a new system call,
+.BR rt_sigreturn ()
+was added to support an enlarged
+.I sigset_t
+type.
+The GNU C library
+hides these details from us, transparently employing
+.BR rt_sigreturn ()
+when the kernel provides it.
+.\"
+.SH SEE ALSO
+.BR kill (2),
+.BR restart_syscall (2),
+.BR sigaltstack (2),
+.BR signal (2),
+.BR getcontext (3),
+.BR signal (7),
+.BR vdso (7)