original/man2/sigaltstack.2

   1 '\" t
   2 .\" Copyright (c) 2001, Michael Kerrisk (mtk.manpages@gmail.com)
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" aeb, various minor fixes
  27 .TH SIGALTSTACK 2 2010-09-26 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 sigaltstack \- set and/or get signal stack context
  30 .SH SYNOPSIS
  31 .B #include <signal.h>
  32 .sp
  33 .BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
  34 .sp
  35 .in -4n
  36 Feature Test Macro Requirements for glibc (see
  37 .BR feature_test_macros (7)):
  38 .in
  39 .sp
  40 .BR sigaltstack ():
  41 .ad l
  42 .RS 4
  43 .PD 0
  44 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  45 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  46 .br
  47 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  48 .PD
  49 .RE
  50 .ad
  51 .SH DESCRIPTION
  52 .BR sigaltstack ()
  53 allows a process to define a new alternate
  54 signal stack and/or retrieve the state of an existing
  55 alternate signal stack.
  56 An alternate signal stack is used during the
  57 execution of a signal handler if the establishment of that handler (see
  58 .BR sigaction (2))
  59 requested it.
  60
  61 The normal sequence of events for using an alternate signal stack
  62 is the following:
  63 .TP 3
  64 1.
  65 Allocate an area of memory to be used for the alternate
  66 signal stack.
  67 .TP
  68 2.
  69 Use
  70 .BR sigaltstack ()
  71 to inform the system of the existence and
  72 location of the alternate signal stack.
  73 .TP
  74 3.
  75 When establishing a signal handler using
  76 .BR sigaction (2),
  77 inform the system that the signal handler should be executed
  78 on the alternate signal stack by
  79 specifying the \fBSA_ONSTACK\fP flag.
  80 .P
  81 The \fIss\fP argument is used to specify a new
  82 alternate signal stack, while the \fIoss\fP argument
  83 is used to retrieve information about the currently
  84 established signal stack.
  85 If we are interested in performing just one
  86 of these tasks, then the other argument can be specified as NULL.
  87 Each of these arguments is a structure of the following type:
  88 .sp
  89 .in +4n
  90 .nf
  91 typedef struct {
  92     void  *ss_sp;     /* Base address of stack */
  93     int    ss_flags;  /* Flags */
  94     size_t ss_size;   /* Number of bytes in stack */
  95 } stack_t;
  96 .fi
  97 .in
  98
  99 To establish a new alternate signal stack,
 100 \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
 101 \fIss.ss_size\fP specify the starting address and size of
 102 the stack.
 103 The constant \fBSIGSTKSZ\fP is defined to be large enough
 104 to cover the usual size requirements for an alternate signal stack,
 105 and the constant \fBMINSIGSTKSZ\fP defines the minimum
 106 size required to execute a signal handler.
 107
 108 When a signal handler is invoked on the alternate stack,
 109 the kernel automatically aligns the address given in \fIss.ss_sp\fP
 110 to a suitable address boundary for the underlying hardware architecture.
 111
 112 To disable an existing stack, specify \fIss.ss_flags\fP
 113 as \fBSS_DISABLE\fP.
 114 In this case, the remaining fields
 115 in \fIss\fP are ignored.
 116
 117 If \fIoss\fP is not NULL, then it is used to return information about
 118 the alternate signal stack which was in effect prior to the
 119 call to
 120 .BR sigaltstack ().
 121 The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
 122 address and size of that stack.
 123 The \fIoss.ss_flags\fP may return either of the following values:
 124 .TP
 125 .B SS_ONSTACK
 126 The process is currently executing on the alternate signal stack.
 127 (Note that it is not possible
 128 to change the alternate signal stack if the process is
 129 currently executing on it.)
 130 .TP
 131 .B SS_DISABLE
 132 The alternate signal stack is currently disabled.
 133 .SH RETURN VALUE
 134 .BR sigaltstack ()
 135 returns 0 on success, or \-1 on failure with
 136 \fIerrno\fP set to indicate the error.
 137 .SH ERRORS
 138 .TP
 139 .B EFAULT
 140 Either \fIss\fP or \fIoss\fP is not NULL and points to an area
 141 outside of the process's address space.
 142 .TP
 143 .B EINVAL
 144 \fIss\fP is not NULL and the \fIss_flags\fP field contains
 145 a nonzero value other than
 146 .BR SS_DISABLE .
 147 .TP
 148 .B ENOMEM
 149 The specified size of the new alternate signal stack
 150 .I ss.ss_size
 151 was less than
 152 .BR MINSTKSZ .
 153 .TP
 154 .B EPERM
 155 An attempt was made to change the alternate signal stack while
 156 it was active (i.e., the process was already executing
 157 on the current alternate signal stack).
 158 .SH CONFORMING TO
 159 SUSv2, SVr4, POSIX.1-2001.
 160 .SH NOTES
 161 The most common usage of an alternate signal stack is to handle the
 162 .B SIGSEGV
 163 signal that is generated if the space available for the
 164 normal process stack is exhausted: in this case, a signal handler for
 165 .B SIGSEGV
 166 cannot be invoked on the process stack; if we wish to handle it,
 167 we must use an alternate signal stack.
 168 .P
 169 Establishing an alternate signal stack is useful if a process
 170 expects that it may exhaust its standard stack.
 171 This may occur, for example, because the stack grows so large
 172 that it encounters the upwardly growing heap, or it reaches a
 173 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
 174 If the standard stack is exhausted, the kernel sends
 175 the process a \fBSIGSEGV\fP signal.
 176 In these circumstances the only way to catch this signal is
 177 on an alternate signal stack.
 178 .P
 179 On most hardware architectures supported by Linux, stacks grow
 180 downward.
 181 .BR sigaltstack ()
 182 automatically takes account
 183 of the direction of stack growth.
 184 .P
 185 Functions called from a signal handler executing on an alternate
 186 signal stack will also use the alternate signal stack.
 187 (This also applies to any handlers invoked for other signals while
 188 the process is executing on the alternate signal stack.)
 189 Unlike the standard stack, the system does not
 190 automatically extend the alternate signal stack.
 191 Exceeding the allocated size of the alternate signal stack will
 192 lead to unpredictable results.
 193 .P
 194 A successful call to
 195 .BR execve (2)
 196 removes any existing alternate
 197 signal stack.
 198 A child process created via
 199 .BR fork (2)
 200 inherits a copy of its parent's alternate signal stack settings.
 201 .P
 202 .BR sigaltstack ()
 203 supersedes the older
 204 .BR sigstack ()
 205 call.
 206 For backward compatibility, glibc also provides
 207 .BR sigstack ().
 208 All new applications should be written using
 209 .BR sigaltstack ().
 210 .SS History
 211 4.2BSD had a
 212 .BR sigstack ()
 213 system call.
 214 It used a slightly
 215 different struct, and had the major disadvantage that the caller
 216 had to know the direction of stack growth.
 217 .SH EXAMPLE
 218 The following code segment demonstrates the use of
 219 .BR sigaltstack ():
 220
 221 .in +4n
 222 .nf
 223 stack_t ss;
 224
 225 ss.ss_sp = malloc(SIGSTKSZ);
 226 if (ss.ss_sp == NULL)
 227     /* Handle error */;
 228 ss.ss_size = SIGSTKSZ;
 229 ss.ss_flags = 0;
 230 if (sigaltstack(&ss, NULL) == \-1)
 231     /* Handle error */;
 232 .fi
 233 .in
 234 .SH SEE ALSO
 235 .BR execve (2),
 236 .BR setrlimit (2),
 237 .BR sigaction (2),
 238 .BR siglongjmp (3),
 239 .BR sigsetjmp (3),
 240 .BR signal (7)
 241 .SH COLOPHON
 242 This page is part of release 3.79 of the Linux
 243 .I man-pages
 244 project.
 245 A description of the project,
 246 information about reporting bugs,
 247 and the latest version of this page,
 248 can be found at
 249 \%http://www.kernel.org/doc/man\-pages/.