1.\" $OpenBSD: sigaltstack.2,v 1.16 2012/11/17 13:09:21 jmc Exp $ 2.\" $NetBSD: sigaltstack.2,v 1.3 1995/02/27 10:41:52 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1992, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)sigaltstack.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: November 17 2012 $ 34.Dt SIGALTSTACK 2 35.Os 36.Sh NAME 37.Nm sigaltstack 38.Nd set and/or get signal stack context 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <signal.h> 42.Bd -literal 43typedef struct sigaltstack { 44 void *ss_sp; 45 size_t ss_size; 46 int ss_flags; 47} stack_t; 48.Ed 49.Ft int 50.Fn sigaltstack "const stack_t *ss" "stack_t *oss" 51.Sh DESCRIPTION 52.Fn sigaltstack 53allows users to define an alternate stack on which signals 54delivered to this thread 55are to be processed. 56If 57.Fa ss 58is non-zero and 59.Dv SS_DISABLE 60is set in 61.Fa ss_flags , 62the signal stack will be disabled. 63A disabled stack will cause all signals to be 64taken on the regular user stack. 65Trying to disable an active stack will cause 66.Nm 67to return \-1 with 68.Va errno 69set to 70.Er EPERM . 71.Pp 72Otherwise, 73.Fa ss_sp 74specifies a pointer to a space to be used as the signal stack and 75.Fa ss_size 76specifies the size of that space. 77When a signal's action indicates its handler 78should execute on the signal stack (specified with a 79.Xr sigaction 2 80call), the system checks to see 81if the thread is currently executing on that stack. 82If the thread is not currently executing on the signal stack, 83the system arranges a switch to the signal stack for the 84duration of the signal handler's execution. 85.Pp 86If 87.Fa oss 88is non-zero, the current signal stack state is returned. 89The 90.Fa ss_flags 91field will contain the value 92.Dv SS_ONSTACK 93if the thread is currently on a signal stack and 94.Dv SS_DISABLE 95if the signal stack is currently disabled. 96.Sh NOTES 97The value 98.Dv SIGSTKSZ 99is defined to be the number of bytes/chars that would be used to cover 100the usual case when allocating an alternate stack area. 101The following code fragment is typically used to allocate an alternate stack. 102.Bd -literal -offset indent 103if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) 104 /* error return */ 105sigstk.ss_size = SIGSTKSZ; 106sigstk.ss_flags = 0; 107if (sigaltstack(&sigstk, 0) == -1) 108 perror("sigaltstack"); 109.Ed 110.Pp 111An alternative approach is provided for programs with signal handlers 112that require a specific amount of stack space other than the default size. 113The value 114.Dv MINSIGSTKSZ 115is defined to be the number of bytes/chars that is required by 116the operating system to implement the alternate stack feature. 117In computing an alternate stack size, 118programs should add 119.Dv MINSIGSTKSZ 120to their stack requirements to allow for the operating system overhead. 121.Pp 122Signal stacks are automatically adjusted for the direction of stack 123growth and alignment requirements. 124Signal stacks may or may not be protected by the hardware and 125are not ``grown'' automatically as is done for the normal stack. 126If the stack overflows and this space is not protected 127unpredictable results may occur. 128.Sh RETURN VALUES 129Upon successful completion, a value of 0 is returned. 130Otherwise, a value of \-1 is returned and 131.Va errno 132is set to indicate the error. 133.Sh ERRORS 134.Fn sigaltstack 135will fail and the signal stack context will remain unchanged 136if one of the following occurs. 137.Bl -tag -width [ENOMEM] 138.It Bq Er EFAULT 139Either 140.Fa ss 141or 142.Fa oss 143points to memory that is not a valid part of the process 144address space. 145.It Bq Er EINVAL 146The 147.Fa ss_flags 148member pointed to by the 149.Fa ss 150argument contains flags other than 151.Dv SS_DISABLE . 152.It Bq Er ENOMEM 153Size of alternate stack area is less than or equal to 154.Dv MINSIGSTKSZ . 155.It Bq Er EPERM 156An attempt was made to disable an active stack. 157.El 158.Sh SEE ALSO 159.Xr sigaction 2 , 160.Xr setjmp 3 161.Sh STANDARDS 162The 163.Nm 164function conforms to 165.St -p1003.1-2008 . 166.Sh HISTORY 167The predecessor to 168.Nm sigaltstack , 169the 170.Fn sigstack 171system call, appeared in 172.Bx 4.2 . 173