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 *ss, stack_t *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 versions <= 2.19: */ _BSD_SOURCE
19

DESCRIPTION

21       sigaltstack()  allows  a process 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 make it safe to switch  away
65                     from  the  signal  handler  with swapcontext(3).  Without
66                     this flag, a subsequently handled signal will corrupt the
67                     state  of  the  switched-away signal handler.  On kernels
68                     where this flag is  not  supported,  sigaltstack()  fails
69                     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
74              automatically 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
92       either of the following values:
93
94       SS_ONSTACK
95              The process is  currently  executing  on  the  alternate  signal
96              stack.   (Note  that  it is not possible to change the alternate
97              signal stack if the process 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  process  is  cur‐
103              rently  executing  on  an alternate signal stack that was estab‐
104              lished using the SS_AUTODISARM flag.  In this case, it  is  safe
105              to  switch away from the signal handler with swapcontext(3).  It
106              is also possible to set up a different alternative signal  stack
107              using a 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
114       obtain  the  current  settings  for  the alternate signal stack without
115       changing 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 MINSTKSZ.
129
130       EPERM  An  attempt  was made to change the alternate signal stack while
131              it was active (i.e., the process was already  executing  on  the
132              current alternate signal stack).
133

ATTRIBUTES

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

CONFORMING TO

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

NOTES

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

EXAMPLE

189       The following code segment demonstrates the use of  sigaltstack()  (and
190       sigaction(2))  to install an alternate signal stack that is employed by
191       a handler for the SIGSEGV signal:
192
193           stack_t ss;
194
195           ss.ss_sp = malloc(SIGSTKSZ);
196           if (ss.ss_sp == NULL) {
197               perror("malloc");
198               exit(EXIT_FAILURE);
199           }
200
201           ss.ss_size = SIGSTKSZ;
202           ss.ss_flags = 0;
203           if (sigaltstack(&ss, NULL) == -1) {
204               perror("sigaltstack");
205               exit(EXIT_FAILURE);
206           }
207
208           sa.sa_flags = SA_ONSTACK;
209           sa.sa_handler = handler();      /* Address of a signal handler */
210           sigemptyset(&sa.sa_mask);
211           if (sigaction(SIGSEGV, &sa, NULL) == -1) {
212               perror("sigaction");
213               exit(EXIT_FAILURE);
214           }
215

BUGS

217       In Linux 2.2 and earlier, the only flag  that  could  be  specified  in
218       ss.sa_flags was SS_DISABLE.  In the lead up to the release of the Linux
219       2.4  kernel,  a  change  was  made  to  allow  sigaltstack()  to  allow
220       ss.ss_flags==SS_ONSTACK  with the same meaning as ss.ss_flags==0 (i.e.,
221       the inclusion of SS_ONSTACK in  ss.ss_flags  is  a  no-op).   On  other
222       implementations, and according to POSIX.1, SS_ONSTACK appears only as a
223       reported flag in old_ss.ss_flags.  On Linux, there is no need  ever  to
224       specify  SS_ONSTACK  in  ss.ss_flags,  and  indeed  doing  so should be
225       avoided on portability grounds: various other systems give an error  if
226       SS_ONSTACK is specified in ss.ss_flags.
227

SEE ALSO

229       execve(2),  setrlimit(2),  sigaction(2),  siglongjmp(3),  sigsetjmp(3),
230       signal(7)
231

COLOPHON

233       This page is part of release 4.15 of the Linux  man-pages  project.   A
234       description  of  the project, information about reporting bugs, and the
235       latest    version    of    this    page,    can     be     found     at
236       https://www.kernel.org/doc/man-pages/.
237
238
239
240Linux                             2017-11-08                    SIGALTSTACK(2)
Impressum