diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:40:15 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:40:15 +0000 |
commit | 399644e47874bff147afb19c89228901ac39340e (patch) | |
tree | 1c4c0b733f4c16b5783b41bebb19194a9ef62ad1 /man2/sigreturn.2 | |
parent | Initial commit. (diff) | |
download | manpages-399644e47874bff147afb19c89228901ac39340e.tar.xz manpages-399644e47874bff147afb19c89228901ac39340e.zip |
Adding upstream version 6.05.01.upstream/6.05.01
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man2/sigreturn.2')
-rw-r--r-- | man2/sigreturn.2 | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 new file mode 100644 index 0000000..03ce952 --- /dev/null +++ b/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 2023-03-30 "Linux man-pages 6.05.01" +.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] +.PP +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 (). +.PP +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.) +.PP +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. +.PP +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. +.PP +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) |