1.\" Copyright (c) 1983, 1991, 1992, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)sigaltstack.2 8.2 (Berkeley) 05/01/95 7.\" 8.Dd 9.Dt SIGALTSTACK 2 10.Os BSD 4.2 11.Sh NAME 12.Nm sigaltstack 13.Nd set and/or get signal stack context 14.Sh SYNOPSIS 15.Fd #include <sys/types.h> 16.Fd #include <signal.h> 17.Bd -literal 18struct sigaltstack { 19 caddr_t ss_base; 20 long ss_size; 21 int ss_flags; 22}; 23.Ed 24.Ft int 25.Fn sigaltstack "const struct sigaltstack *ss" "struct sigaltstack *oss" 26.Sh DESCRIPTION 27.Fn Sigaltstack 28allows users to define an alternate stack on which signals 29are to be processed. 30If 31.Fa ss 32is non-zero, 33it specifies a pointer to and the size of a 34.Em "signal stack" 35on which to deliver signals, 36and tells the system if the process is currently executing 37on that stack. 38When a signal's action indicates its handler 39should execute on the signal stack (specified with a 40.Xr sigaction 2 41call), the system checks to see 42if the process is currently executing on that stack. 43If the process is not currently executing on the signal stack, 44the system arranges a switch to the signal stack for the 45duration of the signal handler's execution. 46.Pp 47If 48.Dv SA_DISABLE 49is set in 50.Fa ss_flags , 51.Fa ss_base 52and 53.Fa ss_size 54are ignored and the signal stack will be disabled. 55Trying to disable an active stack will cause 56.Nm 57to return -1 with 58.Va errno 59set to 60.Dv EINVAL . 61A disabled stack will cause all signals to be 62taken on the regular user stack. 63If the stack is later re-enabled then all signals that were specified 64to be processed on an alternate stack will resume doing so. 65.Pp 66If 67.Fa oss 68is non-zero, the current signal stack state is returned. 69The 70.Fa ss_flags 71field will contain the value 72.Dv SA_ONSTACK 73if the process is currently on a signal stack and 74.Dv SA_DISABLE 75if the signal stack is currently disabled. 76.Sh NOTES 77The value 78.Dv SIGSTKSZ 79is defined to be the number of bytes/chars that would be used to cover 80the usual case when allocating an alternate stack area. 81The following code fragment is typically used to allocate an alternate stack. 82.Bd -literal -offset indent 83if ((sigstk.ss_base = malloc(SIGSTKSZ)) == NULL) 84 /* error return */ 85sigstk.ss_size = SIGSTKSZ; 86sigstk.ss_flags = 0; 87if (sigaltstack(&sigstk,0) < 0) 88 perror("sigaltstack"); 89.Ed 90An alternative approach is provided for programs with signal handlers 91that require a specific amount of stack space other than the default size. 92The value 93.Dv MINSIGSTKSZ 94is defined to be the number of bytes/chars that is required by 95the operating system to implement the alternate stack feature. 96In computing an alternate stack size, 97programs should add 98.Dv MINSIGSTKSZ 99to their stack requirements to allow for the operating system overhead. 100.Pp 101Signal stacks are automatically adjusted for the direction of stack 102growth and alignment requirements. 103Signal stacks may or may not be protected by the hardware and 104are not ``grown'' automatically as is done for the normal stack. 105If the stack overflows and this space is not protected 106unpredictable results may occur. 107.Sh RETURN VALUES 108Upon successful completion, a value of 0 is returned. 109Otherwise, a value of -1 is returned and 110.Va errno 111is set to indicate the error. 112.Sh ERRORS 113.Fn Sigstack 114will fail and the signal stack context will remain unchanged 115if one of the following occurs. 116.Bl -tag -width [ENOMEM] 117.It Bq Er EFAULT 118Either 119.Fa ss 120or 121.Fa oss 122points to memory that is not a valid part of the process 123address space. 124.It Bq Er EINVAL 125An attempt was made to disable an active stack. 126.It Bq Er ENOMEM 127Size of alternate stack area is less than or equal to 128.Dv MINSIGSTKSZ . 129.El 130.Sh SEE ALSO 131.Xr sigaction 2 , 132.Xr setjmp 3 133.Sh HISTORY 134The predecessor to 135.Nm sigaltstack , 136the 137.Fn sigstack 138system call, appeared in 139.Bx 4.2 . 140