1SIGRETURN(2)               Linux Programmer's Manual              SIGRETURN(2)
2
3
4

NAME

6       sigreturn,  rt_sigreturn - return from signal handler and cleanup stack
7       frame
8

SYNOPSIS

10       int sigreturn(...);
11

DESCRIPTION

13       If the Linux kernel determines that an unblocked signal is pending  for
14       a  process,  then,  at  the  next  transition back to user mode in that
15       process (e.g., upon return from a system call or when  the  process  is
16       rescheduled  onto  the  CPU),  it creates a new frame on the user-space
17       stack where it saves various pieces of process context (processor  sta‐
18       tus word, registers, signal mask, and signal stack settings).
19
20       The kernel also arranges that, during the transition back to user mode,
21       the signal handler is called, and that, upon return from  the  handler,
22       control  passes to a piece of user-space code commonly called the "sig‐
23       nal trampoline".  The signal trampoline code in turn calls sigreturn().
24
25       This sigreturn() call undoes  everything  that  was  done—changing  the
26       process's  signal mask, switching signal stacks (see sigaltstack(2))—in
27       order to invoke the signal handler.  Using  the  information  that  was
28       earlier   saved  on  the  user-space  stack  sigreturn()  restores  the
29       process's signal mask, switches stacks, and restores the process's con‐
30       text  (processor  flags  and registers, including the stack pointer and
31       instruction pointer), so that the  process  resumes  execution  at  the
32       point where it was interrupted by the signal.
33

RETURN VALUE

35       sigreturn() never returns.
36

CONFORMING TO

38       Many  UNIX-type  systems have a sigreturn() system call or near equiva‐
39       lent.  However, this call is not specified in POSIX, and details of its
40       behavior vary across systems.
41

NOTES

43       sigreturn() exists only to allow the implementation of signal handlers.
44       It should never be called  directly.   (Indeed,  a  simple  sigreturn()
45       wrapper  in  the  GNU  C  library  simply returns -1, with errno set to
46       ENOSYS.)  Details of the arguments (if any) passed to sigreturn()  vary
47       depending on the architecture.  (On some architectures, such as x86-64,
48       sigreturn() takes no arguments, since all of the  information  that  it
49       requires is available in the stack frame that was previously created by
50       the kernel on the user-space stack.)
51
52       Once upon a time, UNIX systems placed the signal trampoline  code  onto
53       the  user stack.  Nowadays, pages of the user stack are protected so as
54       to disallow code  execution.   Thus,  on  contemporary  Linux  systems,
55       depending  on the architecture, the signal trampoline code lives either
56       in the vdso(7) or in  the  C  library.   In  the  latter  case,  the  C
57       library's sigaction(2) wrapper function informs the kernel of the loca‐
58       tion of the trampoline code by placing its address in  the  sa_restorer
59       field  of the sigaction structure, and sets the SA_RESTORER flag in the
60       sa_flags field.
61
62       The saved process context information is placed in a ucontext_t  struc‐
63       ture (see <sys/ucontext.h>).  That structure is visible within the sig‐
64       nal handler as the third argument of a handler established  via  sigac‐
65       tion(2) with the SA_SIGINFO flag.
66
67       On some other UNIX systems, the operation of the signal trampoline dif‐
68       fers a little.  In particular, on some systems, upon transitioning back
69       to  user mode, the kernel passes control to the trampoline (rather than
70       the signal handler), and the trampoline code calls the  signal  handler
71       (and then calls sigreturn() once the handler returns).
72
73   C library/kernel differences
74       The  original  Linux  system call was named sigreturn().  However, with
75       the addition of real-time signals in Linux  2.2,  a  new  system  call,
76       rt_sigreturn() was added to support an enlarged sigset_t type.  The GNU
77       C  library  hides  these  details  from  us,  transparently   employing
78       rt_sigreturn() when the kernel provides it.
79

SEE ALSO

81       kill(2),  restart_syscall(2), sigaltstack(2), signal(2), getcontext(3),
82       signal(7), vdso(7)
83

COLOPHON

85       This page is part of release 5.02 of the Linux  man-pages  project.   A
86       description  of  the project, information about reporting bugs, and the
87       latest    version    of    this    page,    can     be     found     at
88       https://www.kernel.org/doc/man-pages/.
89
90
91
92Linux                             2017-09-15                      SIGRETURN(2)
Impressum