SIGRETURN(2)              (2017-09-15)               SIGRETURN(2)

     NAME
          sigreturn, rt_sigreturn - return from signal handler and
          cleanup stack frame

     SYNOPSIS
          int sigreturn(...);

     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).

          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 sigreturn().

          This sigreturn() call undoes everything that was done-
          changing the process's signal mask, switching signal stacks
          (see sigaltstack(2))-in order to invoke the signal handler.
          Using the information that was earlier saved on the user-
          space stack sigreturn() restores the process's signal mask,
          switches stacks, and restores the process's context (proces-
          sor 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.

     RETURN VALUE
          sigreturn() never returns.

     CONFORMING TO
          Many UNIX-type systems have a sigreturn() system call or
          near equivalent.  However, this call is not specified in
          POSIX, and details of its behavior vary across systems.

     NOTES
          sigreturn() exists only to allow the implementation of sig-
          nal handlers.  It should never be called directly.  (Indeed,
          a simple sigreturn() wrapper in the GNU C library simply
          returns -1, with errno set to ENOSYS.)  Details of the argu-
          ments (if any) passed to sigreturn() vary depending on the
          architecture.  (On some architectures, such as x86-64,
          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.)

     Page 1                        Linux             (printed 5/24/22)

     SIGRETURN(2)              (2017-09-15)               SIGRETURN(2)

          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 vdso(7) or in
          the C library.  In the latter case, the C library's
          sigaction(2) wrapper function informs the kernel of the
          location of the trampoline code by placing its address in
          the sa_restorer field of the sigaction structure, and sets
          the SA_RESTORER flag in the sa_flags field.

          The saved process context information is placed in a
          ucontext_t structure (see <sys/ucontext.h>). That structure
          is visible within the signal handler as the third argument
          of a handler established via sigaction(2) with the
          SA_SIGINFO flag.

          On some other UNIX systems, the operation of the signal
          trampoline differs a little.  In particular, on some sys-
          tems, 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 sigreturn() once the handler returns).

        C library/kernel differences
          The original Linux system call was named sigreturn().  How-
          ever, with the addition of real-time signals in Linux 2.2, a
          new system call, rt_sigreturn() was added to support an
          enlarged sigset_t type.  The GNU C library hides these
          details from us, transparently employing rt_sigreturn() when
          the kernel provides it.

     SEE ALSO
          kill(2), restart_syscall(2), sigaltstack(2), signal(2),
          getcontext(3), signal(7), vdso(7)

     COLOPHON
          This page is part of release 5.10 of the Linux man-pages
          project.  A description of the project, information about
          reporting bugs, and the latest version of this page, can be
          found at https://www.kernel.org/doc/man-pages/.

     Page 2                        Linux             (printed 5/24/22)