xenial (2) rt_sigreturn.2.gz

Provided by: manpages-dev_4.04-2_all bug

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 saves various pieces of process context (processor status word, registers,
       signal mask, and signal stack settings) into the user-space stack.

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

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 signal handlers.  It should never be called
       directly.  Details of the arguments (if any) passed to 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  vdso(7)  or  in  the  C
       library.   In  the  latter  case,  the  C  library supplies the location of the trampoline code using the
       sa_restorer field of the sigaction structure that is passed to sigaction(2),  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  with  the
       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 sigreturn()
       once the handler returns).

   C library/kernel differences
       The original Linux system call was named sigreturn().  However, 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 4.04 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
       http://www.kernel.org/doc/man-pages/.