xref: /freebsd/lib/libsys/sigaltstack.2 (revision 8269e7673cf033aba67dab8264fe719920c70f87)
1*8269e767SBrooks Davis.\" Copyright (c) 1983, 1991, 1992, 1993
2*8269e767SBrooks Davis.\"	The Regents of the University of California.  All rights reserved.
3*8269e767SBrooks Davis.\"
4*8269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without
5*8269e767SBrooks Davis.\" modification, are permitted provided that the following conditions
6*8269e767SBrooks Davis.\" are met:
7*8269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright
8*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer.
9*8269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright
10*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer in the
11*8269e767SBrooks Davis.\"    documentation and/or other materials provided with the distribution.
12*8269e767SBrooks Davis.\" 3. Neither the name of the University nor the names of its contributors
13*8269e767SBrooks Davis.\"    may be used to endorse or promote products derived from this software
14*8269e767SBrooks Davis.\"    without specific prior written permission.
15*8269e767SBrooks Davis.\"
16*8269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17*8269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18*8269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19*8269e767SBrooks Davis.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20*8269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21*8269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22*8269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23*8269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24*8269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25*8269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26*8269e767SBrooks Davis.\" SUCH DAMAGE.
27*8269e767SBrooks Davis.\"
28*8269e767SBrooks Davis.Dd May 6, 2010
29*8269e767SBrooks Davis.Dt SIGALTSTACK 2
30*8269e767SBrooks Davis.Os
31*8269e767SBrooks Davis.Sh NAME
32*8269e767SBrooks Davis.Nm sigaltstack
33*8269e767SBrooks Davis.Nd set and/or get signal stack context
34*8269e767SBrooks Davis.Sh LIBRARY
35*8269e767SBrooks Davis.Lb libc
36*8269e767SBrooks Davis.Sh SYNOPSIS
37*8269e767SBrooks Davis.In signal.h
38*8269e767SBrooks Davis.Bd -literal
39*8269e767SBrooks Davistypedef struct {
40*8269e767SBrooks Davis        char    *ss_sp;
41*8269e767SBrooks Davis        size_t  ss_size;
42*8269e767SBrooks Davis        int     ss_flags;
43*8269e767SBrooks Davis} stack_t;
44*8269e767SBrooks Davis.Ed
45*8269e767SBrooks Davis.Ft int
46*8269e767SBrooks Davis.Fn sigaltstack "const stack_t * restrict ss" "stack_t * restrict oss"
47*8269e767SBrooks Davis.Sh DESCRIPTION
48*8269e767SBrooks DavisThe
49*8269e767SBrooks Davis.Fn sigaltstack
50*8269e767SBrooks Davissystem call
51*8269e767SBrooks Davisallows defining an alternate stack on which signals
52*8269e767SBrooks Davisare to be processed for the current thread.
53*8269e767SBrooks DavisIf
54*8269e767SBrooks Davis.Fa ss
55*8269e767SBrooks Davisis non-zero,
56*8269e767SBrooks Davisit specifies a pointer to and the size of a
57*8269e767SBrooks Davis.Em "signal stack"
58*8269e767SBrooks Davison which to deliver signals.
59*8269e767SBrooks DavisWhen a signal's action indicates its handler
60*8269e767SBrooks Davisshould execute on the signal stack (specified with a
61*8269e767SBrooks Davis.Xr sigaction 2
62*8269e767SBrooks Davissystem call), the system checks to see
63*8269e767SBrooks Davisif the thread is currently executing on that stack.
64*8269e767SBrooks DavisIf the thread is not currently executing on the signal stack,
65*8269e767SBrooks Davisthe system arranges a switch to the signal stack for the
66*8269e767SBrooks Davisduration of the signal handler's execution.
67*8269e767SBrooks Davis.Pp
68*8269e767SBrooks DavisAn active stack cannot be modified.
69*8269e767SBrooks Davis.Pp
70*8269e767SBrooks DavisIf
71*8269e767SBrooks Davis.Dv SS_DISABLE
72*8269e767SBrooks Davisis set in
73*8269e767SBrooks Davis.Fa ss_flags ,
74*8269e767SBrooks Davis.Fa ss_sp
75*8269e767SBrooks Davisand
76*8269e767SBrooks Davis.Fa ss_size
77*8269e767SBrooks Davisare ignored and the signal stack will be disabled.
78*8269e767SBrooks DavisA disabled stack will cause all signals to be
79*8269e767SBrooks Davistaken on the regular user stack.
80*8269e767SBrooks DavisIf the stack is later re-enabled then all signals that were specified
81*8269e767SBrooks Davisto be processed on an alternate stack will resume doing so.
82*8269e767SBrooks Davis.Pp
83*8269e767SBrooks DavisIf
84*8269e767SBrooks Davis.Fa oss
85*8269e767SBrooks Davisis non-zero, the current signal stack state is returned.
86*8269e767SBrooks DavisThe
87*8269e767SBrooks Davis.Fa ss_flags
88*8269e767SBrooks Davisfield will contain the value
89*8269e767SBrooks Davis.Dv SS_ONSTACK
90*8269e767SBrooks Davisif the thread is currently on a signal stack and
91*8269e767SBrooks Davis.Dv SS_DISABLE
92*8269e767SBrooks Davisif the signal stack is currently disabled.
93*8269e767SBrooks Davis.Sh NOTES
94*8269e767SBrooks DavisThe value
95*8269e767SBrooks Davis.Dv SIGSTKSZ
96*8269e767SBrooks Davisis defined to be the number of bytes/chars that would be used to cover
97*8269e767SBrooks Davisthe usual case when allocating an alternate stack area.
98*8269e767SBrooks DavisThe following code fragment is typically used to allocate an alternate stack.
99*8269e767SBrooks Davis.Bd -literal -offset indent
100*8269e767SBrooks Davisif ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
101*8269e767SBrooks Davis	/* error return */
102*8269e767SBrooks Davissigstk.ss_size = SIGSTKSZ;
103*8269e767SBrooks Davissigstk.ss_flags = 0;
104*8269e767SBrooks Davisif (sigaltstack(&sigstk, NULL) < 0)
105*8269e767SBrooks Davis	perror("sigaltstack");
106*8269e767SBrooks Davis.Ed
107*8269e767SBrooks DavisAn alternative approach is provided for programs with signal handlers
108*8269e767SBrooks Davisthat require a specific amount of stack space other than the default size.
109*8269e767SBrooks DavisThe value
110*8269e767SBrooks Davis.Dv MINSIGSTKSZ
111*8269e767SBrooks Davisis defined to be the number of bytes/chars that is required by
112*8269e767SBrooks Davisthe operating system to implement the alternate stack feature.
113*8269e767SBrooks DavisIn computing an alternate stack size,
114*8269e767SBrooks Davisprograms should add
115*8269e767SBrooks Davis.Dv MINSIGSTKSZ
116*8269e767SBrooks Davisto their stack requirements to allow for the operating system overhead.
117*8269e767SBrooks Davis.Pp
118*8269e767SBrooks DavisSignal stacks are automatically adjusted for the direction of stack
119*8269e767SBrooks Davisgrowth and alignment requirements.
120*8269e767SBrooks DavisSignal stacks may or may not be protected by the hardware and
121*8269e767SBrooks Davisare not ``grown'' automatically as is done for the normal stack.
122*8269e767SBrooks DavisIf the stack overflows and this space is not protected
123*8269e767SBrooks Davisunpredictable results may occur.
124*8269e767SBrooks Davis.Sh RETURN VALUES
125*8269e767SBrooks Davis.Rv -std sigaltstack
126*8269e767SBrooks Davis.Sh ERRORS
127*8269e767SBrooks DavisThe
128*8269e767SBrooks Davis.Fn sigaltstack
129*8269e767SBrooks Davissystem call
130*8269e767SBrooks Daviswill fail and the signal stack context will remain unchanged
131*8269e767SBrooks Davisif one of the following occurs.
132*8269e767SBrooks Davis.Bl -tag -width Er
133*8269e767SBrooks Davis.It Bq Er EFAULT
134*8269e767SBrooks DavisEither
135*8269e767SBrooks Davis.Fa ss
136*8269e767SBrooks Davisor
137*8269e767SBrooks Davis.Fa oss
138*8269e767SBrooks Davispoints to memory that is not a valid part of the process
139*8269e767SBrooks Davisaddress space.
140*8269e767SBrooks Davis.It Bq Er EPERM
141*8269e767SBrooks DavisAn attempt was made to modify an active stack.
142*8269e767SBrooks Davis.It Bq Er EINVAL
143*8269e767SBrooks DavisThe
144*8269e767SBrooks Davis.Fa ss_flags
145*8269e767SBrooks Davisfield was invalid.
146*8269e767SBrooks Davis.It Bq Er ENOMEM
147*8269e767SBrooks DavisSize of alternate stack area is less than or equal to
148*8269e767SBrooks Davis.Dv MINSIGSTKSZ .
149*8269e767SBrooks Davis.El
150*8269e767SBrooks Davis.Sh SEE ALSO
151*8269e767SBrooks Davis.Xr sigaction 2 ,
152*8269e767SBrooks Davis.Xr setjmp 3
153*8269e767SBrooks Davis.Sh HISTORY
154*8269e767SBrooks DavisThe predecessor to
155*8269e767SBrooks Davis.Fn sigaltstack ,
156*8269e767SBrooks Davisthe
157*8269e767SBrooks Davis.Fn sigstack
158*8269e767SBrooks Davissystem call, appeared in
159*8269e767SBrooks Davis.Bx 4.2 .
160