| blob | 08bc398803ed95594d47fca518615a1685240985 |
1 .\" $NetBSD: sigaltstack.2,v 1.23 2012/03/02 18:07:17 joerg Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1992, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)sigaltstack.2 8.2 (Berkeley) 5/1/95
31 .\"
32 .Dd March 2, 2012
33 .Dt SIGALTSTACK 2
34 .Os
35 .Sh NAME
36 .Nm sigaltstack
37 .Nd set and/or get signal stack context
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In signal.h
42 .Pp
43 .Bd -literal
44 typedef struct sigaltstack {
45 void *ss_sp;
46 size_t ss_size;
47 int ss_flags;
48 } stack_t;
49 .Ed
50 .Ft int
51 .Fn sigaltstack "const stack_t * restrict ss" "stack_t * restrict oss"
52 .Sh DESCRIPTION
53 .Fn sigaltstack
54 allows users to define an alternative stack on which signals
55 are to be processed.
56 If
57 .Fa ss
58 is non-zero,
59 it specifies a pointer to and the size of a
60 .Em "signal stack"
61 on which to deliver signals,
62 and tells the system if the process is currently executing
63 on that stack.
64 When a signal's action indicates its handler
65 should execute on the signal stack (specified with a
66 .Xr sigaction 2
67 call), the system checks to see
68 if the process is currently executing on that stack.
69 If the process is not currently executing on the signal stack,
70 the system arranges a switch to the signal stack for the
71 duration of the signal handler's execution.
72 .Pp
73 If
74 .Dv SS_DISABLE
75 is set in
76 .Fa ss_flags ,
77 .Fa ss_sp
78 and
79 .Fa ss_size
80 are ignored and the signal stack will be disabled.
81 Trying to disable an active stack will cause
82 .Nm
83 to return \-1 with
84 .Va errno
85 set to
86 .Er EINVAL .
87 A disabled stack will cause all signals to be
88 taken on the regular user stack.
89 If the stack is later re-enabled then all signals that were specified
90 to be processed on an alternative stack will resume doing so.
91 .Pp
92 If
93 .Fa oss
94 is non-zero, the current signal stack state is returned.
95 The
96 .Fa ss_flags
97 field will contain the value
98 .Dv SS_ONSTACK
99 if the process is currently on a signal stack and
100 .Dv SS_DISABLE
101 if the signal stack is currently disabled.
102 .Sh NOTES
103 The value
104 .Dv SIGSTKSZ
105 is defined to be the number of bytes/chars that would be used to cover
106 the usual case when allocating an alternative stack area.
107 The following code fragment is typically used to allocate an alternative stack.
108 .Bd -literal -offset indent
109 if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
110 /* error return */
111 sigstk.ss_size = SIGSTKSZ;
112 sigstk.ss_flags = 0;
113 if (sigaltstack(\*[Am]sigstk,0) \*[Lt] 0)
114 perror("sigaltstack");
115 .Ed
116 .Pp
117 An alternative approach is provided for programs with signal handlers
118 that require a specific amount of stack space other than the default size.
119 The value
120 .Dv MINSIGSTKSZ
121 is defined to be the number of bytes/chars that is required by
122 the operating system to implement the alternative stack feature.
123 In computing an alternative stack size,
124 programs should add
125 .Dv MINSIGSTKSZ
126 to their stack requirements to allow for the operating system overhead.
127 .Pp
128 Signal stacks are automatically adjusted for the direction of stack
129 growth and alignment requirements.
130 Signal stacks may or may not be protected by the hardware and
131 are not ``grown'' automatically as is done for the normal stack.
132 If the stack overflows and this space is not protected
133 unpredictable results may occur.
134 .Sh RETURN VALUES
135 Upon successful completion, a value of 0 is returned.
136 Otherwise, a value of \-1 is returned and
137 .Va errno
138 is set to indicate the error.
139 .Sh ERRORS
140 .Fn sigaltstack
141 will fail and the signal stack context will remain unchanged
142 if one of the following occurs.
143 .Bl -tag -width Er
144 .It Bq Er EFAULT
145 Either
146 .Fa ss
147 or
148 .Fa oss
149 points to memory that is not a valid part of the process
150 address space.
151 .It Bq Er EINVAL
152 An attempt was made to disable an active stack.
153 .It Bq Er ENOMEM
154 Size of alternative stack area is less than
155 .Dv MINSIGSTKSZ .
156 .El
157 .Sh SEE ALSO
158 .Xr sigaction 2 ,
159 .Xr setjmp 3 ,
160 .Xr signal 7
161 .Sh STANDARDS
162 The
163 .Fn sigaltstack
164 function conforms to
165 .St -xpg4.2 .
166 .Sh HISTORY
167 The predecessor to
168 .Nm sigaltstack ,
169 the
170 .Fn sigstack
171 system call, appeared in
172 .Bx 4.2 .