1.\" $OpenBSD: sigaltstack.2,v 1.23 2018/04/22 13:23:46 deraadt 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: April 22 2018 $ 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.In signal.h 41.Bd -literal 42typedef struct sigaltstack { 43 void *ss_sp; 44 size_t ss_size; 45 int ss_flags; 46} stack_t; 47.Ed 48.Ft int 49.Fn sigaltstack "const stack_t *ss" "stack_t *oss" 50.Sh DESCRIPTION 51.Fn sigaltstack 52allows users to define an alternate stack on which signals 53delivered to this thread 54are to be processed. 55If 56.Fa ss 57is non-zero and 58.Dv SS_DISABLE 59is set in 60.Fa ss_flags , 61the signal stack will be disabled. 62A disabled stack will cause all signals to be 63taken on the regular user stack. 64Trying to disable an active stack will cause 65.Fn sigaltstack 66to return \-1 with 67.Va errno 68set to 69.Er EPERM . 70.Pp 71Otherwise, 72.Fa ss_sp 73specifies a pointer to a space to be used as the signal stack and 74.Fa ss_size 75specifies the size of that space. 76When a signal's action indicates its handler 77should execute on the signal stack (specified with a 78.Xr sigaction 2 79call), the system checks to see 80if the thread is currently executing on that stack. 81If the thread is not currently executing on the signal stack, 82the system arranges a switch to the signal stack for the 83duration of the signal handler's execution. 84.Pp 85If 86.Fa oss 87is non-zero, the current signal stack state is returned. 88The 89.Fa ss_flags 90field will contain the value 91.Dv SS_ONSTACK 92if the thread is currently on a signal stack and 93.Dv SS_DISABLE 94if the signal stack is currently disabled. 95.Pp 96To permit the space to operate as a stack, a page-aligned 97inner region will be zeroed and have 98.Dv MAP_STACK 99(see 100.Xr mmap 2 ) 101enabled. 102Once the sigaltstack is disabled, 103.Dv MAP_STACK 104remains on the memory, so it is best to deallocate the memory 105via a method that results in 106.Xr munmap 2 . 107.Sh NOTES 108The value 109.Dv SIGSTKSZ 110is defined to be the number of bytes/chars that would be used to cover 111the usual case when allocating an alternate stack area. 112The following code fragment is typically used to allocate an alternate stack. 113.Bd -literal -offset indent 114if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) 115 /* error return */ 116sigstk.ss_size = SIGSTKSZ; 117sigstk.ss_flags = 0; 118if (sigaltstack(&sigstk, NULL) == -1) 119 perror("sigaltstack"); 120.Ed 121.Pp 122An alternative approach is provided for programs with signal handlers 123that require a specific amount of stack space other than the default size. 124The value 125.Dv MINSIGSTKSZ 126is defined to be the number of bytes/chars that is required by 127the operating system to implement the alternate stack feature. 128In computing an alternate stack size, 129programs should add 130.Dv MINSIGSTKSZ 131to their stack requirements to allow for the operating system overhead. 132.Pp 133Signal stacks are automatically adjusted for the direction of stack 134growth and alignment requirements. 135Signal stacks may or may not be protected by the hardware and 136are not 137.Dq grown 138automatically as is done for the normal stack. 139If the stack overflows and this space is not protected 140unpredictable results may occur. 141.Sh RETURN VALUES 142.Rv -std 143.Sh ERRORS 144.Fn sigaltstack 145will fail and the signal stack context will remain unchanged 146if one of the following occurs. 147.Bl -tag -width [ENOMEM] 148.It Bq Er EFAULT 149Either 150.Fa ss 151or 152.Fa oss 153points to memory that is not a valid part of the process 154address space. 155.It Bq Er EINVAL 156The 157.Fa ss_flags 158member pointed to by the 159.Fa ss 160argument contains flags other than 161.Dv SS_DISABLE . 162.It Bq Er ENOMEM 163Size of alternate stack area is less than or equal to 164.Dv MINSIGSTKSZ . 165.It Bq Er EPERM 166An attempt was made to disable an active stack. 167.El 168.Sh SEE ALSO 169.Xr sigaction 2 , 170.Xr setjmp 3 171.Sh STANDARDS 172The 173.Fn sigaltstack 174function conforms to 175.St -p1003.1-2008 . 176.Sh HISTORY 177The predecessor to 178.Fn sigaltstack , 179the 180.Fn sigstack 181system call, appeared in 182.Bx 4.2 . 183