man2/sigaltstack.2

   1 '\" t
   2 .\" Copyright (c) 2001, Michael Kerrisk (mtk-manpages@gmx.net)
   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.
  17 .\"
  18 .\" Formatted or processed versions of this manual, if unaccompanied by
  19 .\" the source, must acknowledge the copyright and authors of this work.
  20 .\"
  21 .\" aeb, various minor fixes
  22 .TH SIGALTSTACK 2 2001-09-27 "Linux 2.4" "Linux Programmer's Manual"
  23 .SH NAME
  24 sigaltstack \- set and/or get signal stack context
  25 .SH SYNOPSIS
  26 .B #include <signal.h>
  27 .sp
  28 .BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
  29 .SH DESCRIPTION
  30 \fBsigaltstack\fP() allows a process to define a new alternate
  31 signal stack and/or retrieve the state of an existing
  32 alternate signal stack.  An alternate signal stack is used during the
  33 execution of a signal handler if the establishment of that handler (see
  34 .BR sigaction (2))
  35 requested it.
  36
  37 The normal sequence of events for using an alternate signal stack
  38 is the following:
  39 .TP
  40 1.
  41 Allocate an area of memory to be used for the alternate
  42 signal stack.
  43 .TP
  44 2.
  45 Use \fBsigaltstack\fP() to inform the system of the existence and
  46 location of the alternate signal stack.
  47 .TP
  48 3.
  49 When establishing a signal handler using \fBsigaction\fP(),
  50 inform the system that the signal handler should be executed
  51 on the alternate signal stack by
  52 specifying the \fBSA_ONSTACK\fP flag.
  53 .P
  54 The \fIss\fP argument is used to specify a new
  55 alternate signal stack, while the \fIoss\fP argument
  56 is used to retrieve information about the currently
  57 established signal stack.
  58 If we are interested in performing just one
  59 of these tasks then the other argument can be specified as NULL.
  60 Each of these arguments is a structure of the following type:
  61 .sp
  62 .RS
  63 .nf
  64 typedef struct {
  65     void  *ss_sp;     /* Base address of stack */
  66     int    ss_flags;  /* Flags */
  67     size_t ss_size;   /* Number of bytes in stack */
  68 } stack_t;
  69 .fi
  70 .RE
  71
  72 To establish a new alternate signal stack,
  73 \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
  74 \fIss.ss_size\fP specify the starting address and size of
  75 the stack.
  76 The constant \fBSIGSTKSZ\fP is defined to be large enough
  77 to cover the usual size requirements for an alternate signal stack,
  78 and the constant \fBMINSIGSTKSZ\fP defines the minimum
  79 size required to execute a signal handler.
  80
  81 When a signal handler is invoked on the alternate stack,
  82 the kernel automatically aligns the address given in \fIss.ss_sp\fP
  83 to a suitable address bundary for the underlying hardware architecture.
  84
  85 To disable an existing stack, specify \fIss.ss_flags\fP
  86 as \fBSS_DISABLE\fP.  In this case, the remaining fields
  87 in \fIss\fP are ignored.
  88
  89 If \fIoss\fP is not NULL, then it is used to return information about
  90 the alternate signal stack which was in effect prior to the
  91 call to \fBsigaltstack\fP().
  92 The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
  93 address and size of that stack.
  94 The \fIoss.ss_flags\fP may return either of the following values:
  95 .TP
  96 .B SS_ONSTACK
  97 The process is currently executing on the alternate
  98 signal stack.  (Note that it is not possible
  99 to change the alternate signal stack if the process is
 100 currently executing on it.)
 101 .TP
 102 .B SS_DISABLE
 103 The alternate signal stack is currently disabled.
 104 .SH "RETURN VALUE"
 105 \fBsigaltstack\fP() returns 0 on success, or \-1 on failure with
 106 \fIerrno\fP set to indicate the error.
 107 .SH ERRORS
 108 .TP
 109 .B EFAULT
 110 Either \fIss\fP or \fIoss\fP is not NULL and points to an area
 111 outside of the process's address space.
 112 .TP
 113 .B EINVAL
 114 \fIss\fP is not NULL and the \fPss_flags\fP field contains
 115 a non-zero value other than SS_DISABLE.
 116 .TP
 117 .B ENOMEM
 118 The specified size of the new alternate signal stack
 119 (\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP.
 120 .TP
 121 .B EPERM
 122 An attempt was made to change the alternate signal stack while
 123 it was active (i.e., the process was already executing
 124 on the current alternate signal stack).
 125 .SH NOTES
 126 The most common usage of an alternate signal stack is to handle the
 127 .B SIGSEGV
 128 signal that is generated if the space available for the
 129 normal process stack is exhausted: in this case, a signal handler for
 130 .B SIGSEGV
 131 cannot be invoked on the process stack; if we wish to handle it,
 132 we must use an alternate signal stack.
 133
 134 The following code segment demonstrates the use of \fBsigaltstack\fP():
 135
 136 .RS
 137 .nf
 138 stack_t ss;
 139
 140 ss.ss_sp = malloc(SIGSTKSZ);
 141 if (ss.ss_sp == NULL)
 142     /* Handle error */;
 143 ss.ss_size = SIGSTKSZ;
 144 ss.ss_flags = 0;
 145 if (sigaltstack(&ss, NULL) == \-1)
 146     /* Handle error */;
 147 .fi
 148 .RE
 149 .P
 150 Establishing an alternate signal stack is useful if a process
 151 expects that it may exhaust its standard stack.
 152 This may occur, for example, because the stack grows so large
 153 that it encounters the upwardly growing heap, or it reaches a
 154 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
 155 If the standard stack is exhausted, the kernel sends
 156 the process a \fBSIGSEGV\fP signal.
 157 In these circumstances the only way to catch this signal is
 158 on an alternate signal stack.
 159 .P
 160 On most hardware architectures supported by Linux, stacks grow
 161 downwards.  \fBsigaltstack\fP() automatically takes account
 162 of the direction of stack growth.
 163 .P
 164 Functions called from a signal handler executing on an alternate
 165 signal stack will also use the alternate signal stack.
 166 (This also applies to any handlers invoked for other signals while
 167 the process is executing on the alternate signal stack.)
 168 Unlike the standard stack, the system does not
 169 automatically extend the alternate signal stack.
 170 Exceeding the allocated size of the alternate signal stack will
 171 lead to unpredictable results.
 172 .P
 173 A successful call to \fBexecve\fP() removes any existing alternate
 174 signal stack.
 175 .P
 176 \fBsigaltstack\fP() supersedes the older \fBsigstack\fP() call.
 177 For backwards compatibility, glibc also provides \fBsigstack\fP().
 178 All new applications should be written using \fBsigaltstack\fP().
 179 .SH HISTORY
 180 4.2BSD had a \fIsigstack\fP() system call. It used a slightly
 181 different struct, and had the major disadvantage that the caller
 182 had to know the direction of stack growth.
 183 .SH "CONFORMING TO"
 184 SUSv2, SVr4, POSIX 1003.1-2001.
 185 .SH "SEE ALSO"
 186 .BR execve (2),
 187 .BR setrlimit (2),
 188 .BR sigaction (2),
 189 .BR siglongjmp (3),
 190 .BR sigsetjmp (3),
 191 .BR signal (7)