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.sp_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 To disable an existing stack, specify \fIss.ss_flags\fP
  82 as \fBSS_DISABLE\fP.  In this case, the remaining fields
  83 in \fIss\fP are ignored.
  84
  85 If \fIoss\fP is not NULL, then it is used to return information about
  86 the alternate signal stack which was in effect prior to the
  87 call to \fBsigaltstack\fP.
  88 The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
  89 address and size of that stack.
  90 The \fIoss.ss_flags\fP may return either of the following values:
  91 .TP
  92 .B SS_ONSTACK
  93 The process is currently executing on the alternate
  94 signal stack.  (Note that it is not possible
  95 to change the alternate signal stack if the process is
  96 currently executing on it.)
  97 .TP
  98 .B SS_DISABLE
  99 The alternate signal stack is currently disabled.
 100 .SH "RETURN VALUE"
 101 \fBsigaltstack\fP returns 0 on success, or \-1 on failure with
 102 \fIerrno\fP set to indicate the error.
 103 .SH ERRORS
 104 .TP
 105 .B EFAULT
 106 Either \fIss\fP or \fIoss\fP is not NULL and points to an area
 107 outside of the process's address space.
 108 .TP
 109 .B EINVAL
 110 \fIss\fP is not NULL and the \fPss_flags\fP field contains
 111 a non-zero value other than SS_DISABLE.
 112 .TP
 113 .B ENOMEM
 114 The specified size of the new alternate signal stack
 115 (\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP.
 116 .TP
 117 .B EPERM
 118 An attempt was made to change the alternate signal stack while
 119 it was active (i.e., the process was already executing
 120 on the current alternate signal stack).
 121 .SH NOTES
 122 The following code segment demonstrates the use of \fBsigaltstack\fP:
 123
 124 .RS
 125 .nf
 126 stack_t ss;
 127
 128 ss.ss_sp = malloc(SIGSTKSZ);
 129 if (ss.ss_sp == NULL)
 130     /* Handle error */;
 131 ss.ss_size = SIGSTKSZ;
 132 ss.ss_flags = 0;
 133 if (sigaltstack(&ss, NULL) == \-1)
 134     /* Handle error */;
 135 .fi
 136 .RE
 137 .P
 138 Establishing an alternate signal stack is useful if a process
 139 expects that it may exhaust its standard stack.
 140 This may occur, for example, because the stack grows so large
 141 that it encounters the upwardly growing heap, or it reaches a
 142 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
 143 If the standard stack is exhausted, the kernel sends
 144 the process a \fBSIGSEGV\fP signal.
 145 In these circumstances the only way to catch this signal is
 146 on an alternate signal stack.
 147 .P
 148 On most hardware architectures supported by Linux, stacks grow
 149 downwards.  \fBsigaltstack\fP automatically takes account
 150 of the direction of stack growth.
 151 .P
 152 Functions called from a signal handler executing on an alternate
 153 signal stack will also use the alternate signal stack.
 154 (This also applies to any handlers invoked for other signals while
 155 the process is executing on the alternate signal stack.)
 156 Unlike the standard stack, the system does not
 157 automatically extend the alternate signal stack.
 158 Exceeding the allocated size of the alternate signal stack will
 159 lead to unpredictable results.
 160 .P
 161 A successful call to \fBexecve\fP removes any existing alternate
 162 signal stack.
 163 .P
 164 \fBsigaltstack\fP supersedes the older \fBsigstack\fP call.
 165 For backwards compatibility, glibc also provides \fBsigstack\fP.
 166 All new applications should be written using \fBsigaltstack\fB.
 167 .SH HISTORY
 168 4.2BSD had a \fIsigstack\fP() system call. It used a slightly
 169 different struct, and had as major disadvantage that the caller
 170 had to know the direction of stack growth.
 171 .SH "CONFORMING TO"
 172 SUSv2, SVr4, POSIX 1003.1-2001.
 173 .SH "SEE ALSO"
 174 .BR execve (2),
 175 .BR setrlimit (2),
 176 .BR sigaction (2),
 177 .BR siglongjmp (3),
 178 .BR sigsetjmp (3),
 179 .BR signal (7)