1.\" $OpenBSD: sigaltstack.2,v 1.27 2024/03/29 06:48:04 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: March 29 2024 $ 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 96The value 97.Dv SIGSTKSZ 98is defined to be the number of bytes/chars that would be used to cover 99the usual case when allocating an alternate stack area. 100The following code fragment is typically used to allocate an alternate stack. 101.Bd -literal -offset indent 102if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) 103 /* error return */ 104sigstk.ss_size = SIGSTKSZ; 105sigstk.ss_flags = 0; 106if (sigaltstack(&sigstk, NULL) == -1) 107 perror("sigaltstack"); 108.Ed 109.Pp 110An alternative approach is provided for programs with signal handlers 111that require a specific amount of stack space other than the default size. 112The value 113.Dv MINSIGSTKSZ 114is defined to be the number of bytes/chars that is required by 115the operating system to implement the alternate stack feature. 116In computing an alternate stack size, 117programs should add 118.Dv MINSIGSTKSZ 119to their stack requirements to allow for the operating system overhead. 120.Pp 121Signal stacks are automatically adjusted for the direction of stack 122growth and alignment requirements. 123Signal stacks may or may not be protected by the hardware and 124are not 125.Dq grown 126automatically as is done for the normal stack. 127If the stack overflows and this space is not protected, 128unpredictable results may occur. 129.Pp 130On 131.Ox 132some additional restrictions prevent dangerous address space modifications. 133The proposed space at 134.Fa ss_sp 135is verified to be contiguously mapped for read-write permissions without 136execute. 137If those conditions are met, a page-aligned inner region will be freshly mapped 138(all zero) with 139.Dv MAP_STACK 140(see 141.Xr mmap 2 ) , 142destroying the pre-existing data in the region. 143Once the sigaltstack is disabled, the 144.Dv MAP_STACK 145attribute remains on the memory, so it is best to deallocate the memory 146via a method that results in 147.Xr munmap 2 . 148.Sh RETURN VALUES 149.Rv -std 150.Sh ERRORS 151.Fn sigaltstack 152will fail and the signal stack context will remain unchanged 153if one of the following occurs. 154.Bl -tag -width [ENOMEM] 155.It Bq Er EFAULT 156Either 157.Fa ss 158or 159.Fa oss 160points to memory that is not a valid part of the process 161address space. 162.It Bq Er EINVAL 163The 164.Fa ss_flags 165member pointed to by the 166.Fa ss 167argument contains flags other than 168.Dv SS_DISABLE . 169.It Bq Er EINVAL 170The memory region is not acceptable for use as a stack; 171see above. 172.It Bq Er ENOMEM 173Size of alternate stack area is less than or equal to 174.Dv MINSIGSTKSZ . 175.It Bq Er EPERM 176An attempt was made to disable an active stack. 177.El 178.Sh SEE ALSO 179.Xr sigaction 2 , 180.Xr setjmp 3 181.Sh STANDARDS 182The 183.Fn sigaltstack 184function conforms to 185.St -p1003.1-2008 . 186.Sh HISTORY 187The predecessor to 188.Fn sigaltstack , 189the 190.Fn sigstack 191system call, appeared in 192.Bx 4.2 . 193