usr/src/man/man2/sigaltstack.2

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH SIGALTSTACK 2 "Nov 1, 2003"
  48 .SH NAME
  49 sigaltstack \- set or get signal alternate stack context
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <signal.h>
  54
  55 \fBint\fR \fBsigaltstack\fR(\fBconst stack_t *restrict\fR \fIss\fR, \fBstack_t *restrict\fR \fIoss\fR);
  56 .fi
  57
  58 .SH DESCRIPTION
  59 .sp
  60 .LP
  61 The \fBsigaltstack()\fR function allows a thread to define and examine the
  62 state of an alternate stack area on which signals are processed. If \fIss\fR is
  63 non-zero, it specifies a pointer to and the size of a stack area on which to
  64 deliver signals, and informs the system whether the thread is currently
  65 executing on that stack.  When a signal's action indicates its handler should
  66 execute on the alternate signal stack (specified with a \fBsigaction\fR(2)
  67 call), the system checks whether the thread chosen to execute the signal
  68 handler is currently executing on that stack. If the thread is not currently
  69 executing on the signal stack, the system arranges a switch to the alternate
  70 signal stack for the duration of the signal handler's execution.
  71 .sp
  72 .LP
  73 The  \fBstack_t\fR structure includes the following members:
  74 .sp
  75 .in +2
  76 .nf
  77 int   *ss_sp
  78 long  ss_size
  79 int   ss_flags
  80 .fi
  81 .in -2
  82
  83 .sp
  84 .LP
  85 If \fIss\fR is not \fINULL\fR, it points to a structure specifying the
  86 alternate signal stack that will take effect upon successful return from
  87 \fBsigaltstack()\fR. The \fBss_sp\fR and \fBss_size\fR members specify the new
  88 base and size of the stack, which is automatically adjusted for direction of
  89 growth and alignment.  The \fBss_flags\fR member specifies the new stack state
  90 and may be set to the following:
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBSS_DISABLE\fR\fR
  95 .ad
  96 .RS 14n
  97 The stack is to be disabled and \fBss_sp\fR and \fBss_size\fR are ignored. If
  98 \fBSS_DISABLE\fR is not set, the stack will be enabled.
  99 .RE
 100
 101 .sp
 102 .LP
 103 If \fIoss\fR is not \fINULL\fR, it points to a structure specifying the
 104 alternate signal stack that was in effect prior to the call to
 105 \fBsigaltstack()\fR. The \fBss_sp\fR and \fBss_size\fR members specify the base
 106 and size of that stack.  The \fBss_flags\fR member specifies the stack's state,
 107 and may contain the following values:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBSS_ONSTACK\fR\fR
 112 .ad
 113 .RS 14n
 114 The thread is currently executing on the alternate signal stack. Attempts to
 115 modify the alternate signal stack while the thread is executing on it will
 116 fail.
 117 .RE
 118
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fBSS_DISABLE\fR\fR
 123 .ad
 124 .RS 14n
 125 The alternate signal stack is currently disabled.
 126 .RE
 127
 128 .SH RETURN VALUES
 129 .sp
 130 .LP
 131 Upon successful completion, \fB0\fR is return. Otherwise, \fB\(mi1\fR is
 132 returned and \fBerrno\fR is set to indicate the error.
 133 .SH ERRORS
 134 .sp
 135 .LP
 136 The \fBsigaltstack()\fR function will fail if:
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBEFAULT\fR\fR
 141 .ad
 142 .RS 10n
 143 The \fIss\fR or \fIoss\fR argument points to an illegal address.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBEINVAL\fR\fR
 150 .ad
 151 .RS 10n
 152 The \fIss\fR argument is not a null pointer, and the \fBss_flags\fR member
 153 pointed to by \fIss\fR contains flags other than \fBSS_DISABLE\fR.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBENOMEM\fR\fR
 160 .ad
 161 .RS 10n
 162 The size of the alternate stack area is less than \fBMINSIGSTKSZ\fR.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBEPERM\fR\fR
 169 .ad
 170 .RS 10n
 171 An attempt was made to modify an active stack.
 172 .RE
 173
 174 .SH ATTRIBUTES
 175 .sp
 176 .LP
 177 See \fBattributes\fR(5) for descriptions of the following attributes:
 178 .sp
 179
 180 .sp
 181 .TS
 182 box;
 183 c | c
 184 l | l .
 185 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 186 _
 187 Interface Stability     Standard
 188 _
 189 MT-Level        Async-Signal-Safe
 190 .TE
 191
 192 .SH SEE ALSO
 193 .sp
 194 .LP
 195 \fBgetcontext\fR(2), \fBmmap\fR(2), \fBsigaction\fR(2),
 196 \fBucontext.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5)
 197 .SH NOTES
 198 .sp
 199 .LP
 200 The value \fBSIGSTKSZ\fR is defined to be the number of bytes that would be
 201 used to cover the usual case when allocating an alternate  stack area.  The
 202 value \fBMINSIGSTKSZ\fR is defined to be the minimum stack size for a signal
 203 handler.  In computing an alternate stack size, a program  should add that
 204 amount to its stack requirements to allow for the operating system overhead.
 205 .sp
 206 .LP
 207 The following code fragment is typically used to allocate an alternate stack
 208 with an adjacent red zone (an unmapped page) to guard against stack overflow,
 209 as with default stacks:
 210 .sp
 211 .in +2
 212 .nf
 213 #include <signal.h>
 214 #include <sys/mman.h>
 215
 216 stack_t sigstk;
 217 sigstk.ss_sp = mmap(NULL, SIGSTKSZ, PROT_READ | PROT_WRITE,
 218         MAP_PRIVATE | MAP_ANON, -1, 0);
 219 if (sigstk.ss_sp == MAP_FAILED)
 220         /* error return */;
 221 sigstk.ss_size = SIGSTKSZ;
 222 sigstk.ss_flags = 0;
 223 if (sigaltstack(&sigstk, NULL) < 0)
 224         perror("sigaltstack");
 225 .fi
 226 .in -2
 227