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