1 /* Page fault handling library.
2 Copyright (C) 1998-2023 Free Software Foundation, Inc.
3
4 This program is free software: you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see <https://www.gnu.org/licenses/>. */
16
17 /* Written by Bruno Haible. */
18
19 #ifndef _SIGSEGV_H
20 #define _SIGSEGV_H
21
22 /* Get size_t. */
23 #include <stddef.h>
24
25 /* Define the fault context structure. */
26 #if (defined __linux__ && !defined __ANDROID__) \
27 || (defined __FreeBSD__ && (defined __arm__ || defined __armhf__ || defined __arm64__)) \
28 || defined __NetBSD__ \
29 || defined _AIX || defined __sun \
30 || defined __CYGWIN__
31 /* Linux, FreeBSD, NetBSD, AIX, Solaris, Cygwin */
32 # include <ucontext.h>
33 #elif (defined __APPLE__ && defined __MACH__)
34 /* macOS */
35 # include <sys/ucontext.h>
36 #elif defined __HAIKU__
37 /* Haiku */
38 # include <signal.h>
39 #endif
40
41 /* Correct the value of SIGSTKSZ on some systems.
42 glibc >= 2.34: When _GNU_SOURCE is defined, SIGSTKSZ is no longer a
43 compile-time constant. But most programs need a simple constant.
44 AIX 64-bit: original value 4096 is too small.
45 HP-UX: original value 8192 is too small.
46 Solaris 11/x86_64: original value 8192 is too small. */
47 #include <signal.h>
48 #if __GLIBC__ >= 2
49 # undef SIGSTKSZ
50 # if defined __ia64__
51 # define SIGSTKSZ 262144
52 # else
53 # define SIGSTKSZ 65536
54 # endif
55 #endif
56 #if defined _AIX && defined _ARCH_PPC64
57 # undef SIGSTKSZ
58 # define SIGSTKSZ 8192
59 #endif
60 #if defined __hpux || (defined __sun && (defined __x86_64__ || defined __amd64__))
61 # undef SIGSTKSZ
62 # define SIGSTKSZ 16384
63 #endif
64
65 /* HAVE_SIGSEGV_RECOVERY
66 is defined if the system supports catching SIGSEGV. */
67 #if defined __linux__ || defined __ANDROID__ || defined __GNU__ \
68 || defined __FreeBSD_kernel__ || (defined __FreeBSD__ && !(defined __sparc__ || defined __sparc64__)) || defined __DragonFly__ \
69 || defined __NetBSD__ \
70 || defined __OpenBSD__ \
71 || (defined __APPLE__ && defined __MACH__) \
72 || defined _AIX || defined __sgi || defined __sun \
73 || defined __CYGWIN__ || defined __HAIKU__
74 /* Linux, Hurd, GNU/kFreeBSD, FreeBSD, NetBSD, OpenBSD, macOS, AIX, IRIX, Solaris, Cygwin, Haiku */
75 # define HAVE_SIGSEGV_RECOVERY 1
76 #endif
77
78 /* HAVE_STACK_OVERFLOW_RECOVERY
79 is defined if stack overflow can be caught. */
80 #if defined __linux__ || defined __ANDROID__ || defined __GNU__ \
81 || defined __FreeBSD_kernel__ || (defined __FreeBSD__ && !(defined __sparc__ || defined __sparc64__)) || defined __DragonFly__ \
82 || (defined __NetBSD__ && !(defined __sparc__ || defined __sparc64__)) \
83 || defined __OpenBSD__ \
84 || (defined __APPLE__ && defined __MACH__) \
85 || defined _AIX || defined __sgi || defined __sun \
86 || defined __CYGWIN__ || defined __HAIKU__
87 /* Linux, Hurd, GNU/kFreeBSD, FreeBSD, NetBSD, OpenBSD, macOS, AIX, IRIX, Solaris, Cygwin, Haiku */
88 # define HAVE_STACK_OVERFLOW_RECOVERY 1
89 #endif
90
91
92 #ifdef __cplusplus
93 extern "C" {
94 #endif
95
96 #define LIBSIGSEGV_VERSION 0x020D /* version number: (major<<8) + minor */
97 extern int libsigsegv_version; /* Likewise */
98
99 /* -------------------------------------------------------------------------- */
100
101 #if 1 /* really only HAVE_SIGSEGV_RECOVERY */
102
103 /*
104 * The mask of bits that are set to zero in a fault address that gets passed
105 * to a global SIGSEGV handler.
106 * On some platforms, the precise fault address is not known, only the memory
107 * page into which the fault address falls. This is apparently allowed by POSIX:
108 * <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html>
109 * says: "For some implementations, the value of si_addr may be inaccurate."
110 * In this case, the returned fault address is rounded down to a multiple of
111 * getpagesize() = sysconf(_SC_PAGESIZE).
112 * On such platforms, we define SIGSEGV_FAULT_ADDRESS_ALIGNMENT to be an upper
113 * bound for getpagesize() (and, like getpagesize(), also a power of 2).
114 * On the platforms where the returned fault address is the precise one, we
115 * define SIGSEGV_FAULT_ADDRESS_ALIGNMENT to 1.
116 */
117 # if defined __NetBSD__ && (defined __sparc__ || defined __sparc64__)
118 /* getpagesize () is 0x1000 or 0x2000, depending on hardware. */
119 # define SIGSEGV_FAULT_ADDRESS_ALIGNMENT 0x2000UL
120 # elif defined __linux__ && (defined __s390__ || defined __s390x__)
121 /* getpagesize () is 0x1000. */
122 # define SIGSEGV_FAULT_ADDRESS_ALIGNMENT 0x1000UL
123 # else
124 # define SIGSEGV_FAULT_ADDRESS_ALIGNMENT 1UL
125 # endif
126
127 /*
128 * The type of a global SIGSEGV handler.
129 * The fault address, with the bits (SIGSEGV_FAULT_ADDRESS_ALIGNMENT - 1)
130 * cleared, is passed as argument.
131 * The access type (read access or write access) is not passed; your handler
132 * has to know itself how to distinguish these two cases.
133 * The second argument is 0, meaning it could also be a stack overflow, or 1,
134 * meaning the handler should seriously try to fix the fault.
135 * The return value should be nonzero if the handler has done its job
136 * and no other handler should be called, or 0 if the handler declines
137 * responsibility for the given address.
138 *
139 * The handler is run at a moment when nothing about the global state of the
140 * program is known. Therefore it cannot use facilities that manipulate global
141 * variables or locks. In particular, it cannot use malloc(); use mmap()
142 * instead. It cannot use fopen(); use open() instead. Etc. All global
143 * variables that are accessed by the handler should be marked 'volatile'.
144 */
145 typedef int (*sigsegv_handler_t) (void* fault_address, int serious);
146
147 /*
148 * Installs a global SIGSEGV handler.
149 * This should be called once only, and it ignores any previously installed
150 * SIGSEGV handler.
151 * Returns 0 on success, or -1 if the system doesn't support catching SIGSEGV.
152 */
153 extern int sigsegv_install_handler (sigsegv_handler_t handler);
154
155 /*
156 * Deinstalls the global SIGSEGV handler.
157 * This goes back to the state where no SIGSEGV handler is installed.
158 */
159 extern void sigsegv_deinstall_handler (void);
160
161 /*
162 * Prepares leaving a SIGSEGV handler (through longjmp or similar means).
163 * Control is transferred by calling CONTINUATION with CONT_ARG1, CONT_ARG2,
164 * CONT_ARG3 as arguments.
165 * CONTINUATION must not return.
166 * The sigsegv_leave_handler function may return if called from a SIGSEGV
167 * handler; its return value should be used as the handler's return value.
168 * The sigsegv_leave_handler function does not return if called from a
169 * stack overflow handler.
170 */
171 extern int sigsegv_leave_handler (void (*continuation) (void*, void*, void*), void* cont_arg1, void* cont_arg2, void* cont_arg3);
172
173 #endif /* HAVE_SIGSEGV_RECOVERY */
174
175 #if 1 /* really only HAVE_STACK_OVERFLOW_RECOVERY */
176
177 /*
178 * The type of a context passed to a stack overflow handler.
179 * This type is system dependent; on some platforms it is an 'ucontext_t *',
180 * on some platforms it is a 'struct sigcontext *', on others merely an
181 * opaque 'void *'.
182 */
183 # if (defined __linux__ && !defined __ANDROID__) \
184 || (defined __FreeBSD__ && (defined __arm__ || defined __armhf__ || defined __arm64__)) \
185 || defined __NetBSD__ \
186 || (defined __APPLE__ && defined __MACH__) \
187 || defined _AIX || defined __sun \
188 || defined __CYGWIN__ || defined __HAIKU__
189 typedef ucontext_t *stackoverflow_context_t;
190 # elif defined __GNU__ \
191 || defined __FreeBSD_kernel__ || (defined __FreeBSD__ && !(defined __sparc__ || defined __sparc64__)) || defined __DragonFly__ \
192 || defined __OpenBSD__ || defined __sgi
193 typedef struct sigcontext *stackoverflow_context_t;
194 # else
195 typedef void *stackoverflow_context_t;
196 # endif
197
198 /*
199 * The type of a stack overflow handler.
200 * Such a handler should perform a longjmp call in order to reduce the amount
201 * of stack needed. It must not return.
202 * The emergency argument is 0 when the stack could be repared, or 1 if the
203 * application should better save its state and exit now.
204 *
205 * The handler is run at a moment when nothing about the global state of the
206 * program is known. Therefore it cannot use facilities that manipulate global
207 * variables or locks. In particular, it cannot use malloc(); use mmap()
208 * instead. It cannot use fopen(); use open() instead. Etc. All global
209 * variables that are accessed by the handler should be marked 'volatile'.
210 */
211 typedef void (*stackoverflow_handler_t) (int emergency, stackoverflow_context_t scp);
212
213 /*
214 * Installs a stack overflow handler.
215 * The extra_stack argument is a pointer to a pre-allocated area used as a
216 * stack for executing the handler. It typically comes from a static variable
217 * or from heap-allocated memoty; placing it on the main stack may fail on
218 * some operating systems.
219 * Its size, passed in extra_stack_size, should be sufficiently large. The
220 * following code determines an appropriate size:
221 * #include <signal.h>
222 * #ifndef SIGSTKSZ / * glibc defines SIGSTKSZ for this purpose * /
223 * # define SIGSTKSZ 16384 / * on most platforms, 16 KB are sufficient * /
224 * #endif
225 * Returns 0 on success, or -1 if the system doesn't support catching stack
226 * overflow.
227 */
228 extern int stackoverflow_install_handler (stackoverflow_handler_t handler,
229 void* extra_stack, size_t extra_stack_size);
230
231 /*
232 * Deinstalls the stack overflow handler.
233 */
234 extern void stackoverflow_deinstall_handler (void);
235
236 #endif /* HAVE_STACK_OVERFLOW_RECOVERY */
237
238 /* -------------------------------------------------------------------------- */
239
240 #ifdef __cplusplus
241 }
242 #endif
243
244 #endif /* _SIGSEGV_H */