1.\" $OpenBSD: sigaltstack.2,v 1.21 2018/03/21 16:22:21 gsoares 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 21 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 96The stack must be allocated using 97.Xr mmap 2 98with 99.Ar MAP_STACK 100to inform the kernel that the memory is being used as a stack. 101Otherwise, the first system call performed while operating on 102that stack will deliver 103.Dv SIGABRT . 104.Sh NOTES 105The value 106.Dv SIGSTKSZ 107is defined to be the number of bytes/chars that would be used to cover 108the usual case when allocating an alternate stack area. 109The following code fragment is typically used to allocate an alternate stack. 110.Bd -literal -offset indent 111if ((sigstk.ss_sp = mmap(NULL, SIGSTKSZ, PROT_WRITE | PROT_READ, 112 MAP_PRIVATE | MAP_ANON | MAP_STACK, -1, 0)) == MAP_FAILED) 113 /* error return */ 114sigstk.ss_size = SIGSTKSZ; 115sigstk.ss_flags = 0; 116if (sigaltstack(&sigstk, 0) == -1) 117 perror("sigaltstack"); 118.Ed 119.Pp 120An alternative approach is provided for programs with signal handlers 121that require a specific amount of stack space other than the default size. 122The value 123.Dv MINSIGSTKSZ 124is defined to be the number of bytes/chars that is required by 125the operating system to implement the alternate stack feature. 126In computing an alternate stack size, 127programs should add 128.Dv MINSIGSTKSZ 129to their stack requirements to allow for the operating system overhead. 130.Pp 131Signal stacks are automatically adjusted for the direction of stack 132growth and alignment requirements. 133Signal stacks may or may not be protected by the hardware and 134are not 135.Dq grown 136automatically as is done for the normal stack. 137If the stack overflows and this space is not protected 138unpredictable results may occur. 139.Sh RETURN VALUES 140.Rv -std 141.Sh ERRORS 142.Fn sigaltstack 143will fail and the signal stack context will remain unchanged 144if one of the following occurs. 145.Bl -tag -width [ENOMEM] 146.It Bq Er EFAULT 147Either 148.Fa ss 149or 150.Fa oss 151points to memory that is not a valid part of the process 152address space. 153.It Bq Er EINVAL 154The 155.Fa ss_flags 156member pointed to by the 157.Fa ss 158argument contains flags other than 159.Dv SS_DISABLE . 160.It Bq Er ENOMEM 161Size of alternate stack area is less than or equal to 162.Dv MINSIGSTKSZ . 163.It Bq Er EPERM 164An attempt was made to disable an active stack. 165.El 166.Sh SEE ALSO 167.Xr sigaction 2 , 168.Xr setjmp 3 169.Sh STANDARDS 170The 171.Fn sigaltstack 172function conforms to 173.St -p1003.1-2008 . 174.Sh HISTORY 175The predecessor to 176.Fn sigaltstack , 177the 178.Fn sigstack 179system call, appeared in 180.Bx 4.2 . 181