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