1.\" $OpenBSD: sigaltstack.2,v 1.18 2014/11/15 14:41:02 bentley 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 15 2014 $ 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.Nm 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.Sh NOTES 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, 0) == -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.Sh RETURN VALUES 130.Rv -std 131.Sh ERRORS 132.Fn sigaltstack 133will fail and the signal stack context will remain unchanged 134if one of the following occurs. 135.Bl -tag -width [ENOMEM] 136.It Bq Er EFAULT 137Either 138.Fa ss 139or 140.Fa oss 141points to memory that is not a valid part of the process 142address space. 143.It Bq Er EINVAL 144The 145.Fa ss_flags 146member pointed to by the 147.Fa ss 148argument contains flags other than 149.Dv SS_DISABLE . 150.It Bq Er ENOMEM 151Size of alternate stack area is less than or equal to 152.Dv MINSIGSTKSZ . 153.It Bq Er EPERM 154An attempt was made to disable an active stack. 155.El 156.Sh SEE ALSO 157.Xr sigaction 2 , 158.Xr setjmp 3 159.Sh STANDARDS 160The 161.Nm 162function conforms to 163.St -p1003.1-2008 . 164.Sh HISTORY 165The predecessor to 166.Nm sigaltstack , 167the 168.Fn sigstack 169system call, appeared in 170.Bx 4.2 . 171