man2/sigaltstack.2

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