man2/sigaltstack.2

   1 .\" Copyright (c) 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" aeb, various minor fixes
   6 .TH SIGALTSTACK 2 2022-09-09 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 sigaltstack \- set and/or get signal stack context
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <signal.h>
  15 .PP
  16 .BI "int sigaltstack(const stack_t *restrict " ss \
  17 ", stack_t *restrict " old_ss );
  18 .fi
  19 .PP
  20 .RS -4
  21 Feature Test Macro Requirements for glibc (see
  22 .BR feature_test_macros (7)):
  23 .RE
  24 .PP
  25 .BR sigaltstack ():
  26 .nf
  27     _XOPEN_SOURCE >= 500
  28 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  29         || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
  30         || /* Glibc <= 2.19: */ _BSD_SOURCE
  31 .fi
  32 .SH DESCRIPTION
  33 .BR sigaltstack ()
  34 allows a thread to define a new alternate
  35 signal stack and/or retrieve the state of an existing
  36 alternate signal stack.
  37 An alternate signal stack is used during the
  38 execution of a signal handler if the establishment of that handler (see
  39 .BR sigaction (2))
  40 requested it.
  41 .PP
  42 The normal sequence of events for using an alternate signal stack
  43 is the following:
  44 .TP 3
  45 1.
  46 Allocate an area of memory to be used for the alternate
  47 signal stack.
  48 .TP
  49 2.
  50 Use
  51 .BR sigaltstack ()
  52 to inform the system of the existence and
  53 location of the alternate signal stack.
  54 .TP
  55 3.
  56 When establishing a signal handler using
  57 .BR sigaction (2),
  58 inform the system that the signal handler should be executed
  59 on the alternate signal stack by
  60 specifying the \fBSA_ONSTACK\fP flag.
  61 .PP
  62 The \fIss\fP argument is used to specify a new
  63 alternate signal stack, while the \fIold_ss\fP argument
  64 is used to retrieve information about the currently
  65 established signal stack.
  66 If we are interested in performing just one
  67 of these tasks, then the other argument can be specified as NULL.
  68 .PP
  69 The
  70 .I stack_t
  71 type used to type the arguments of this function is defined as follows:
  72 .PP
  73 .in +4n
  74 .EX
  75 typedef struct {
  76     void  *ss_sp;     /* Base address of stack */
  77     int    ss_flags;  /* Flags */
  78     size_t ss_size;   /* Number of bytes in stack */
  79 } stack_t;
  80 .EE
  81 .in
  82 .PP
  83 To establish a new alternate signal stack,
  84 the fields of this structure are set as follows:
  85 .TP
  86 .I ss.ss_flags
  87 This field contains either 0, or the following flag:
  88 .RS
  89 .TP
  90 .BR SS_AUTODISARM " (since Linux 4.7)"
  91 .\" commit 2a74213838104a41588d86fd5e8d344972891ace
  92 .\" See tools/testing/selftests/sigaltstack/sas.c in kernel sources
  93 Clear the alternate signal stack settings on entry to the signal handler.
  94 When the signal handler returns,
  95 the previous alternate signal stack settings are restored.
  96 .IP
  97 This flag was added in order to make it safe
  98 to switch away from the signal handler with
  99 .BR swapcontext (3).
 100 Without this flag, a subsequently handled signal will corrupt
 101 the state of the switched-away signal handler.
 102 On kernels where this flag is not supported,
 103 .BR sigaltstack ()
 104 fails with the error
 105 .B EINVAL
 106 when this flag is supplied.
 107 .RE
 108 .TP
 109 .I ss.ss_sp
 110 This field specifies the starting address of the stack.
 111 When a signal handler is invoked on the alternate stack,
 112 the kernel automatically aligns the address given in \fIss.ss_sp\fP
 113 to a suitable address boundary for the underlying hardware architecture.
 114 .TP
 115 .I ss.ss_size
 116 This field specifies the size of the stack.
 117 The constant \fBSIGSTKSZ\fP is defined to be large enough
 118 to cover the usual size requirements for an alternate signal stack,
 119 and the constant \fBMINSIGSTKSZ\fP defines the minimum
 120 size required to execute a signal handler.
 121 .PP
 122 To disable an existing stack, specify \fIss.ss_flags\fP
 123 as \fBSS_DISABLE\fP.
 124 In this case, the kernel ignores any other flags in
 125 .I ss.ss_flags
 126 and the remaining fields
 127 in \fIss\fP.
 128 .PP
 129 If \fIold_ss\fP is not NULL, then it is used to return information about
 130 the alternate signal stack which was in effect prior to the
 131 call to
 132 .BR sigaltstack ().
 133 The \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting
 134 address and size of that stack.
 135 The \fIold_ss.ss_flags\fP may return either of the following values:
 136 .TP
 137 .B SS_ONSTACK
 138 The thread is currently executing on the alternate signal stack.
 139 (Note that it is not possible
 140 to change the alternate signal stack if the thread is
 141 currently executing on it.)
 142 .TP
 143 .B SS_DISABLE
 144 The alternate signal stack is currently disabled.
 145 .IP
 146 Alternatively, this value is returned if the thread is currently
 147 executing on an alternate signal stack that was established using the
 148 .B SS_AUTODISARM
 149 flag.
 150 In this case, it is safe to switch away from the signal handler with
 151 .BR swapcontext (3).
 152 It is also possible to set up a different alternative signal stack
 153 using a further call to
 154 .BR sigaltstack ().
 155 .\" FIXME Was it intended that one can set up a different alternative
 156 .\" signal stack in this scenario? (In passing, if one does this, the
 157 .\" sigaltstack(NULL, &old_ss) now returns old_ss.ss_flags==SS_AUTODISARM
 158 .\" rather than old_ss.ss_flags==SS_DISABLE. The API design here seems
 159 .\" confusing...
 160 .TP
 161 .B SS_AUTODISARM
 162 The alternate signal stack has been marked to be autodisarmed
 163 as described above.
 164 .PP
 165 By specifying
 166 .I ss
 167 as NULL, and
 168 .I old_ss
 169 as a non-NULL value, one can obtain the current settings for
 170 the alternate signal stack without changing them.
 171 .SH RETURN VALUE
 172 .BR sigaltstack ()
 173 returns 0 on success, or \-1 on failure with
 174 \fIerrno\fP set to indicate the error.
 175 .SH ERRORS
 176 .TP
 177 .B EFAULT
 178 Either \fIss\fP or \fIold_ss\fP is not NULL and points to an area
 179 outside of the process's address space.
 180 .TP
 181 .B EINVAL
 182 \fIss\fP is not NULL and the \fIss_flags\fP field contains
 183 an invalid flag.
 184 .TP
 185 .B ENOMEM
 186 The specified size of the new alternate signal stack
 187 .I ss.ss_size
 188 was less than
 189 .BR MINSIGSTKSZ .
 190 .TP
 191 .B EPERM
 192 An attempt was made to change the alternate signal stack while
 193 it was active (i.e., the thread was already executing
 194 on the current alternate signal stack).
 195 .SH ATTRIBUTES
 196 For an explanation of the terms used in this section, see
 197 .BR attributes (7).
 198 .ad l
 199 .nh
 200 .TS
 201 allbox;
 202 lbx lb lb
 203 l l l.
 204 Interface       Attribute       Value
 205 T{
 206 .BR sigaltstack ()
 207 T}      Thread safety   MT-Safe
 208 .TE
 209 .hy
 210 .ad
 211 .sp 1
 212 .SH STANDARDS
 213 POSIX.1-2001, POSIX.1-2008, SUSv2, SVr4.
 214 .PP
 215 The
 216 .B SS_AUTODISARM
 217 flag is a Linux extension.
 218 .SH NOTES
 219 The most common usage of an alternate signal stack is to handle the
 220 .B SIGSEGV
 221 signal that is generated if the space available for the
 222 standard stack is exhausted: in this case, a signal handler for
 223 .B SIGSEGV
 224 cannot be invoked on the standard stack; if we wish to handle it,
 225 we must use an alternate signal stack.
 226 .PP
 227 Establishing an alternate signal stack is useful if a thread
 228 expects that it may exhaust its standard stack.
 229 This may occur, for example, because the stack grows so large
 230 that it encounters the upwardly growing heap, or it reaches a
 231 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
 232 If the standard stack is exhausted, the kernel sends
 233 the thread a \fBSIGSEGV\fP signal.
 234 In these circumstances the only way to catch this signal is
 235 on an alternate signal stack.
 236 .PP
 237 On most hardware architectures supported by Linux, stacks grow
 238 downward.
 239 .BR sigaltstack ()
 240 automatically takes account
 241 of the direction of stack growth.
 242 .PP
 243 Functions called from a signal handler executing on an alternate
 244 signal stack will also use the alternate signal stack.
 245 (This also applies to any handlers invoked for other signals while
 246 the thread is executing on the alternate signal stack.)
 247 Unlike the standard stack, the system does not
 248 automatically extend the alternate signal stack.
 249 Exceeding the allocated size of the alternate signal stack will
 250 lead to unpredictable results.
 251 .PP
 252 A successful call to
 253 .BR execve (2)
 254 removes any existing alternate
 255 signal stack.
 256 A child process created via
 257 .BR fork (2)
 258 inherits a copy of its parent's alternate signal stack settings.
 259 The same is also true for a child process created using
 260 .BR clone (2),
 261 unless the clone flags include
 262 .B CLONE_VM
 263 and do not include
 264 .BR CLONE_VFORK ,
 265 in which case any alternate signal stack that was established in the parent
 266 is disabled in the child process.
 267 .PP
 268 .BR sigaltstack ()
 269 supersedes the older
 270 .BR sigstack ()
 271 call.
 272 For backward compatibility, glibc also provides
 273 .BR sigstack ().
 274 All new applications should be written using
 275 .BR sigaltstack ().
 276 .SS History
 277 4.2BSD had a
 278 .BR sigstack ()
 279 system call.
 280 It used a slightly
 281 different struct, and had the major disadvantage that the caller
 282 had to know the direction of stack growth.
 283 .SH BUGS
 284 In Linux 2.2 and earlier, the only flag that could be specified
 285 in
 286 .I ss.sa_flags
 287 was
 288 .BR SS_DISABLE .
 289 In the lead up to the release of the Linux 2.4 kernel,
 290 .\" Linux 2.3.40
 291 .\" After quite a bit of web and mail archive searching,
 292 .\" I could not find the patch on any mailing list, and I
 293 .\" could find no place where the rationale for this change
 294 .\" explained -- mtk
 295 a change was made to allow
 296 .BR sigaltstack ()
 297 to allow
 298 .I ss.ss_flags==SS_ONSTACK
 299 with the same meaning as
 300 .I ss.ss_flags==0
 301 (i.e., the inclusion of
 302 .B SS_ONSTACK
 303 in
 304 .I ss.ss_flags
 305 is a no-op).
 306 On other implementations, and according to POSIX.1,
 307 .B SS_ONSTACK
 308 appears only as a reported flag in
 309 .IR old_ss.ss_flags .
 310 On Linux, there is no need ever to specify
 311 .B SS_ONSTACK
 312 in
 313 .IR ss.ss_flags ,
 314 and indeed doing so should be avoided on portability grounds:
 315 various other systems
 316 .\" See the source code of Illumos and FreeBSD, for example.
 317 give an error if
 318 .B SS_ONSTACK
 319 is specified in
 320 .IR ss.ss_flags .
 321 .SH EXAMPLES
 322 The following code segment demonstrates the use of
 323 .BR sigaltstack ()
 324 (and
 325 .BR sigaction (2))
 326 to install an alternate signal stack that is employed by a handler
 327 for the
 328 .B SIGSEGV
 329 signal:
 330 .PP
 331 .in +4n
 332 .EX
 333 stack_t ss;
 334
 335 ss.ss_sp = malloc(SIGSTKSZ);
 336 if (ss.ss_sp == NULL) {
 337     perror("malloc");
 338     exit(EXIT_FAILURE);
 339 }
 340
 341 ss.ss_size = SIGSTKSZ;
 342 ss.ss_flags = 0;
 343 if (sigaltstack(&ss, NULL) == \-1) {
 344     perror("sigaltstack");
 345     exit(EXIT_FAILURE);
 346 }
 347
 348 sa.sa_flags = SA_ONSTACK;
 349 sa.sa_handler = handler();      /* Address of a signal handler */
 350 sigemptyset(&sa.sa_mask);
 351 if (sigaction(SIGSEGV, &sa, NULL) == \-1) {
 352     perror("sigaction");
 353     exit(EXIT_FAILURE);
 354 }
 355 .EE
 356 .in
 357 .SH SEE ALSO
 358 .BR execve (2),
 359 .BR setrlimit (2),
 360 .BR sigaction (2),
 361 .BR siglongjmp (3),
 362 .BR sigsetjmp (3),
 363 .BR signal (7)