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

NAME

6       sigaltstack - set and/or get signal stack context
7

SYNOPSIS

9       #include <signal.h>
10
11       int sigaltstack(const stack_t *restrict ss, stack_t *restrict old_ss);
12
13   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14
15       sigaltstack():
16           _XOPEN_SOURCE >= 500
17               || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
18               || /* Glibc <= 2.19: */ _BSD_SOURCE
19

DESCRIPTION

21       sigaltstack()  allows  a  thread to define a new alternate signal stack
22       and/or retrieve the state of an existing alternate  signal  stack.   An
23       alternate signal stack is used during the execution of a signal handler
24       if the establishment of that handler (see sigaction(2)) requested it.
25
26       The normal sequence of events for using an alternate  signal  stack  is
27       the following:
28
29       1. Allocate  an  area  of  memory  to  be used for the alternate signal
30          stack.
31
32       2. Use sigaltstack() to inform the system of the existence and location
33          of the alternate signal stack.
34
35       3. When  establishing  a  signal handler using sigaction(2), inform the
36          system that the signal handler should be executed on  the  alternate
37          signal stack by specifying the SA_ONSTACK flag.
38
39       The  ss argument is used to specify a new alternate signal stack, while
40       the old_ss argument is used to retrieve information about the currently
41       established  signal stack.  If we are interested in performing just one
42       of these tasks, then the other argument can be specified as NULL.
43
44       The stack_t type used to type the arguments of this function is defined
45       as follows:
46
47           typedef struct {
48               void  *ss_sp;     /* Base address of stack */
49               int    ss_flags;  /* Flags */
50               size_t ss_size;   /* Number of bytes in stack */
51           } stack_t;
52
53       To establish a new alternate signal stack, the fields of this structure
54       are set as follows:
55
56       ss.ss_flags
57              This field contains either 0, or the following flag:
58
59              SS_AUTODISARM (since Linux 4.7)
60                     Clear the alternate signal stack settings on entry to the
61                     signal  handler.   When  the  signal handler returns, the
62                     previous alternate signal stack settings are restored.
63
64                     This flag was added in order to make it  safe  to  switch
65                     away  from the signal handler with swapcontext(3).  With‐
66                     out this flag, a subsequently handled signal will corrupt
67                     the  state  of the switched-away signal handler.  On ker‐
68                     nels where this  flag  is  not  supported,  sigaltstack()
69                     fails with the error EINVAL when this flag is supplied.
70
71       ss.ss_sp
72              This  field specifies the starting address of the stack.  When a
73              signal handler is invoked on the alternate stack, the kernel au‐
74              tomatically  aligns  the address given in ss.ss_sp to a suitable
75              address boundary for the underlying hardware architecture.
76
77       ss.ss_size
78              This field specifies  the  size  of  the  stack.   The  constant
79              SIGSTKSZ  is  defined to be large enough to cover the usual size
80              requirements for an alternate signal  stack,  and  the  constant
81              MINSIGSTKSZ  defines the minimum size required to execute a sig‐
82              nal handler.
83
84       To disable an existing stack, specify ss.ss_flags  as  SS_DISABLE.   In
85       this  case,  the  kernel ignores any other flags in ss.ss_flags and the
86       remaining fields in ss.
87
88       If old_ss is not NULL, then it is used to return information about  the
89       alternate signal stack which was in effect prior to the call to sigalt‐
90       stack().  The old_ss.ss_sp and old_ss.ss_size fields return the  start‐
91       ing address and size of that stack.  The old_ss.ss_flags may return ei‐
92       ther of the following values:
93
94       SS_ONSTACK
95              The thread is currently executing on the alternate signal stack.
96              (Note  that  it  is  not possible to change the alternate signal
97              stack if the thread is currently executing on it.)
98
99       SS_DISABLE
100              The alternate signal stack is currently disabled.
101
102              Alternatively, this value is returned if the thread is currently
103              executing  on an alternate signal stack that was established us‐
104              ing the SS_AUTODISARM flag.  In this case, it is safe to  switch
105              away  from  the  signal handler with swapcontext(3).  It is also
106              possible to set up a different alternative signal stack using  a
107              further call to sigaltstack().
108
109       SS_AUTODISARM
110              The alternate signal stack has been marked to be autodisarmed as
111              described above.
112
113       By specifying ss as NULL, and old_ss as a non-NULL value, one  can  ob‐
114       tain the current settings for the alternate signal stack without chang‐
115       ing them.
116

RETURN VALUE

118       sigaltstack() returns 0 on success, or -1 on failure with errno set  to
119       indicate the error.
120

ERRORS

122       EFAULT Either ss or old_ss is not NULL and points to an area outside of
123              the process's address space.
124
125       EINVAL ss is not NULL and the ss_flags field contains an invalid flag.
126
127       ENOMEM The specified size of the new alternate signal stack  ss.ss_size
128              was less than MINSIGSTKSZ.
129
130       EPERM  An  attempt  was made to change the alternate signal stack while
131              it was active (i.e., the thread was  already  executing  on  the
132              current alternate signal stack).
133

ATTRIBUTES

135       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
136       tributes(7).
137
138       ┌────────────────────────────────────────────┬───────────────┬─────────┐
139Interface                                   Attribute     Value   
140       ├────────────────────────────────────────────┼───────────────┼─────────┤
141sigaltstack()                               │ Thread safety │ MT-Safe │
142       └────────────────────────────────────────────┴───────────────┴─────────┘
143

CONFORMING TO

145       POSIX.1-2001, POSIX.1-2008, SUSv2, SVr4.
146
147       The SS_AUTODISARM flag is a Linux extension.
148

NOTES

150       The most common usage of an alternate signal stack  is  to  handle  the
151       SIGSEGV  signal  that is generated if the space available for the stan‐
152       dard stack is exhausted: in this case, a  signal  handler  for  SIGSEGV
153       cannot  be  invoked  on the standard stack; if we wish to handle it, we
154       must use an alternate signal stack.
155
156       Establishing an alternate signal stack is useful if  a  thread  expects
157       that  it  may exhaust its standard stack.  This may occur, for example,
158       because the stack grows so large that it encounters the upwardly  grow‐
159       ing  heap,  or  it  reaches  a  limit established by a call to setrlim‐
160       it(RLIMIT_STACK, &rlim).  If the standard stack is exhausted, the  ker‐
161       nel sends the thread a SIGSEGV signal.  In these circumstances the only
162       way to catch this signal is on an alternate signal stack.
163
164       On most hardware architectures supported by Linux,  stacks  grow  down‐
165       ward.   sigaltstack()  automatically  takes account of the direction of
166       stack growth.
167
168       Functions called from a signal handler executing on an alternate signal
169       stack  will also use the alternate signal stack.  (This also applies to
170       any handlers invoked for other signals while the thread is executing on
171       the  alternate  signal  stack.)   Unlike the standard stack, the system
172       does not automatically extend the alternate  signal  stack.   Exceeding
173       the  allocated  size  of the alternate signal stack will lead to unpre‐
174       dictable results.
175
176       A successful call to execve(2) removes any  existing  alternate  signal
177       stack.  A child process created via fork(2) inherits a copy of its par‐
178       ent's alternate signal stack settings.  The same is  also  true  for  a
179       child  process  created  using clone(2), unless the clone flags include
180       CLONE_VM and do not include CLONE_VFORK, in which  case  any  alternate
181       signal  stack  that  was  established  in the parent is disabled in the
182       child process.
183
184       sigaltstack() supersedes the older sigstack() call.  For backward  com‐
185       patibility,  glibc  also  provides  sigstack().   All  new applications
186       should be written using sigaltstack().
187
188   History
189       4.2BSD had a sigstack() system call.   It  used  a  slightly  different
190       struct,  and had the major disadvantage that the caller had to know the
191       direction of stack growth.
192

BUGS

194       In Linux 2.2 and earlier, the only flag  that  could  be  specified  in
195       ss.sa_flags was SS_DISABLE.  In the lead up to the release of the Linux
196       2.4  kernel,  a  change  was  made  to  allow  sigaltstack()  to  allow
197       ss.ss_flags==SS_ONSTACK  with the same meaning as ss.ss_flags==0 (i.e.,
198       the inclusion of SS_ONSTACK in ss.ss_flags is a no-op).  On  other  im‐
199       plementations,  and  according to POSIX.1, SS_ONSTACK appears only as a
200       reported flag in old_ss.ss_flags.  On Linux, there is no need  ever  to
201       specify SS_ONSTACK in ss.ss_flags, and indeed doing so should be avoid‐
202       ed on portability grounds: various  other  systems  give  an  error  if
203       SS_ONSTACK is specified in ss.ss_flags.
204

EXAMPLES

206       The  following  code segment demonstrates the use of sigaltstack() (and
207       sigaction(2)) to install an alternate signal stack that is employed  by
208       a handler for the SIGSEGV signal:
209
210           stack_t ss;
211
212           ss.ss_sp = malloc(SIGSTKSZ);
213           if (ss.ss_sp == NULL) {
214               perror("malloc");
215               exit(EXIT_FAILURE);
216           }
217
218           ss.ss_size = SIGSTKSZ;
219           ss.ss_flags = 0;
220           if (sigaltstack(&ss, NULL) == -1) {
221               perror("sigaltstack");
222               exit(EXIT_FAILURE);
223           }
224
225           sa.sa_flags = SA_ONSTACK;
226           sa.sa_handler = handler();      /* Address of a signal handler */
227           sigemptyset(&sa.sa_mask);
228           if (sigaction(SIGSEGV, &sa, NULL) == -1) {
229               perror("sigaction");
230               exit(EXIT_FAILURE);
231           }
232

SEE ALSO

234       execve(2),  setrlimit(2),  sigaction(2),  siglongjmp(3),  sigsetjmp(3),
235       signal(7)
236

COLOPHON

238       This page is part of release 5.12 of the Linux  man-pages  project.   A
239       description  of  the project, information about reporting bugs, and the
240       latest    version    of    this    page,    can     be     found     at
241       https://www.kernel.org/doc/man-pages/.
242
243
244
245Linux                             2021-03-22                    SIGALTSTACK(2)
Impressum