mirror of https://github.com/mkerrisk/man-pages
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>
This commit is contained in:
Michael Kerrisk
parent
4c886933f9
commit
eda078d47b
|
|
@ -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
|
||||
call to
|
||||
.BR sigreturn ()
|
||||
is inserted into the stack frame so that upon
|
||||
return from the signal handler,
|
||||
.BR sigreturn ()
|
||||
will be called.
|
||||
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 saves various pieces of process context
|
||||
(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:
|
||||
it restores the process's signal mask, switches stacks,
|
||||
and restores the process's context (registers, processor flags),
|
||||
so that the process directly resumes execution
|
||||
order to invoke the signal handler.
|
||||
It 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 CONFORMING TO
|
||||
Many UNIX-type systems have a
|
||||
.BR sigreturn ()
|
||||
is specific to Linux and should not be used in programs intended to be
|
||||
portable.
|
||||
system call or near equivalent.
|
||||
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
|
||||
.I __unused
|
||||
argument varies depending on the architecture.
|
||||
Details of the arguments (if any) passed to
|
||||
.BR sigreturn ()
|
||||
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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue