man2/sigaltstack.2

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