original/man2/sigaltstack.2

   1 '\" t
   2 .\" Copyright (c) 2001, Michael Kerrisk (mtk.manpages@gmail.com)
   3 .\"
   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 .\"
  24 .\" aeb, various minor fixes
  25 .TH SIGALTSTACK 2 2010-09-26 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 sigaltstack \- set and/or get signal stack context
  28 .SH SYNOPSIS
  29 .B #include <signal.h>
  30 .sp
  31 .BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
  32 .sp
  33 .in -4n
  34 Feature Test Macro Requirements for glibc (see
  35 .BR feature_test_macros (7)):
  36 .in
  37 .sp
  38 .BR sigaltstack ():
  39 .ad l
  40 .RS 4
  41 .PD 0
  42 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  43 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  44 .br
  45 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  46 .PD
  47 .RE
  48 .ad
  49 .SH DESCRIPTION
  50 .BR sigaltstack ()
  51 allows a process 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
  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 .P
  79 The \fIss\fP argument is used to specify a new
  80 alternate signal stack, while the \fIoss\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 Each of these arguments is a structure of the following type:
  86 .sp
  87 .in +4n
  88 .nf
  89 typedef struct {
  90     void  *ss_sp;     /* Base address of stack */
  91     int    ss_flags;  /* Flags */
  92     size_t ss_size;   /* Number of bytes in stack */
  93 } stack_t;
  94 .fi
  95 .in
  96
  97 To establish a new alternate signal stack,
  98 \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
  99 \fIss.ss_size\fP specify the starting address and size of
 100 the stack.
 101 The constant \fBSIGSTKSZ\fP is defined to be large enough
 102 to cover the usual size requirements for an alternate signal stack,
 103 and the constant \fBMINSIGSTKSZ\fP defines the minimum
 104 size required to execute a signal handler.
 105
 106 When a signal handler is invoked on the alternate stack,
 107 the kernel automatically aligns the address given in \fIss.ss_sp\fP
 108 to a suitable address boundary for the underlying hardware architecture.
 109
 110 To disable an existing stack, specify \fIss.ss_flags\fP
 111 as \fBSS_DISABLE\fP.
 112 In this case, the remaining fields
 113 in \fIss\fP are ignored.
 114
 115 If \fIoss\fP is not NULL, then it is used to return information about
 116 the alternate signal stack which was in effect prior to the
 117 call to
 118 .BR sigaltstack ().
 119 The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
 120 address and size of that stack.
 121 The \fIoss.ss_flags\fP may return either of the following values:
 122 .TP
 123 .B SS_ONSTACK
 124 The process is currently executing on the alternate signal stack.
 125 (Note that it is not possible
 126 to change the alternate signal stack if the process is
 127 currently executing on it.)
 128 .TP
 129 .B SS_DISABLE
 130 The alternate signal stack is currently disabled.
 131 .SH "RETURN VALUE"
 132 .BR sigaltstack ()
 133 returns 0 on success, or \-1 on failure with
 134 \fIerrno\fP set to indicate the error.
 135 .SH ERRORS
 136 .TP
 137 .B EFAULT
 138 Either \fIss\fP or \fIoss\fP is not NULL and points to an area
 139 outside of the process's address space.
 140 .TP
 141 .B EINVAL
 142 \fIss\fP is not NULL and the \fIss_flags\fP field contains
 143 a nonzero value other than
 144 .BR SS_DISABLE .
 145 .TP
 146 .B ENOMEM
 147 The specified size of the new alternate signal stack
 148 (\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP.
 149 .TP
 150 .B EPERM
 151 An attempt was made to change the alternate signal stack while
 152 it was active (i.e., the process was already executing
 153 on the current alternate signal stack).
 154 .SH "CONFORMING TO"
 155 SUSv2, SVr4, POSIX.1-2001.
 156 .SH NOTES
 157 The most common usage of an alternate signal stack is to handle the
 158 .B SIGSEGV
 159 signal that is generated if the space available for the
 160 normal process stack is exhausted: in this case, a signal handler for
 161 .B SIGSEGV
 162 cannot be invoked on the process stack; if we wish to handle it,
 163 we must use an alternate signal stack.
 164 .P
 165 Establishing an alternate signal stack is useful if a process
 166 expects that it may exhaust its standard stack.
 167 This may occur, for example, because the stack grows so large
 168 that it encounters the upwardly growing heap, or it reaches a
 169 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
 170 If the standard stack is exhausted, the kernel sends
 171 the process a \fBSIGSEGV\fP signal.
 172 In these circumstances the only way to catch this signal is
 173 on an alternate signal stack.
 174 .P
 175 On most hardware architectures supported by Linux, stacks grow
 176 downward.
 177 .BR sigaltstack ()
 178 automatically takes account
 179 of the direction of stack growth.
 180 .P
 181 Functions called from a signal handler executing on an alternate
 182 signal stack will also use the alternate signal stack.
 183 (This also applies to any handlers invoked for other signals while
 184 the process is executing on the alternate signal stack.)
 185 Unlike the standard stack, the system does not
 186 automatically extend the alternate signal stack.
 187 Exceeding the allocated size of the alternate signal stack will
 188 lead to unpredictable results.
 189 .P
 190 A successful call to
 191 .BR execve (2)
 192 removes any existing alternate
 193 signal stack.
 194 A child process created via
 195 .BR fork ()
 196 inherits a copy of its parent's alternate signal stack settings.
 197 .P
 198 .BR sigaltstack ()
 199 supersedes the older
 200 .BR sigstack ()
 201 call.
 202 For backward compatibility, glibc also provides
 203 .BR sigstack ().
 204 All new applications should be written using
 205 .BR sigaltstack ().
 206 .SS History
 207 4.2BSD had a
 208 .BR sigstack ()
 209 system call.
 210 It used a slightly
 211 different struct, and had the major disadvantage that the caller
 212 had to know the direction of stack growth.
 213 .SH EXAMPLE
 214 The following code segment demonstrates the use of
 215 .BR sigaltstack ():
 216
 217 .in +4n
 218 .nf
 219 stack_t ss;
 220
 221 ss.ss_sp = malloc(SIGSTKSZ);
 222 if (ss.ss_sp == NULL)
 223     /* Handle error */;
 224 ss.ss_size = SIGSTKSZ;
 225 ss.ss_flags = 0;
 226 if (sigaltstack(&ss, NULL) == \-1)
 227     /* Handle error */;
 228 .fi
 229 .in
 230 .SH "SEE ALSO"
 231 .BR execve (2),
 232 .BR setrlimit (2),
 233 .BR sigaction (2),
 234 .BR siglongjmp (3),
 235 .BR sigsetjmp (3),
 236 .BR signal (7)