1 /* Page fault handling library.
2 Copyright (C) 1998-1999, 2002, 2004-2010 Bruno Haible <bruno@clisp.org>
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, or (at your option)
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.
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software Foundation,
16 Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */
21 @FAULT_CONTEXT_INCLUDE@
23 /* HAVE_SIGSEGV_RECOVERY
24 is defined if the system supports catching SIGSEGV. */
25 #if @HAVE_SIGSEGV_RECOVERY@
26 # define HAVE_SIGSEGV_RECOVERY 1
29 /* HAVE_STACK_OVERFLOW_RECOVERY
30 is defined if stack overflow can be caught. */
31 #if @HAVE_STACK_OVERFLOW_RECOVERY@
32 # define HAVE_STACK_OVERFLOW_RECOVERY 1
40 #define LIBSIGSEGV_VERSION 0x0209 /* version number: (major<<8) + minor */
41 extern int libsigsegv_version
; /* Likewise */
43 /* -------------------------------------------------------------------------- */
46 * The type of a global SIGSEGV handler.
47 * The fault address is passed as argument.
48 * The access type (read access or write access) is not passed; your handler
49 * has to know itself how to distinguish these two cases.
50 * The second argument is 0, meaning it could also be a stack overflow, or 1,
51 * meaning the handler should seriously try to fix the fault.
52 * The return value should be nonzero if the handler has done its job
53 * and no other handler should be called, or 0 if the handler declines
54 * responsibility for the given address.
56 * The handler is run at a moment when nothing about the global state of the
57 * program is known. Therefore it cannot use facilities that manipulate global
58 * variables or locks. In particular, it cannot use malloc(); use mmap()
59 * instead. It cannot use fopen(); use open() instead. Etc. All global
60 * variables that are accessed by the handler should be marked 'volatile'.
62 typedef int (*sigsegv_handler_t
) (void* fault_address
, int serious
);
65 * Installs a global SIGSEGV handler.
66 * This should be called once only, and it ignores any previously installed
68 * Returns 0 on success, or -1 if the system doesn't support catching SIGSEGV.
70 extern int sigsegv_install_handler (sigsegv_handler_t handler
);
73 * Deinstalls the global SIGSEGV handler.
74 * This goes back to the state where no SIGSEGV handler is installed.
76 extern void sigsegv_deinstall_handler (void);
78 #if LIBSIGSEGV_VERSION >= 0x0206
80 * Prepares leaving a SIGSEGV handler (through longjmp or similar means).
81 * Control is transferred by calling CONTINUATION with CONT_ARG1, CONT_ARG2,
82 * CONT_ARG3 as arguments.
83 * CONTINUATION must not return.
84 * The sigsegv_leave_handler function may return if called from a SIGSEGV
85 * handler; its return value should be used as the handler's return value.
86 * The sigsegv_leave_handler function does not return if called from a
87 * stack overflow handler.
89 extern int sigsegv_leave_handler (void (*continuation
) (void*, void*, void*), void* cont_arg1
, void* cont_arg2
, void* cont_arg3
);
90 #else /* older versions of libsigsegv */
92 * Prepares leaving a SIGSEGV handler (through longjmp or similar means).
93 * Limitation: This function could only be called once on MacOS X.
95 extern void sigsegv_leave_handler (void);
99 * The type of a context passed to a stack overflow handler.
100 * This type is system dependent; on some platforms it is an 'ucontext_t *',
101 * on some platforms it is a 'struct sigcontext *', on others merely an
104 typedef @FAULT_CONTEXT@
*stackoverflow_context_t
;
107 * The type of a stack overflow handler.
108 * Such a handler should perform a longjmp call in order to reduce the amount
109 * of stack needed. It must not return.
110 * The emergency argument is 0 when the stack could be repared, or 1 if the
111 * application should better save its state and exit now.
113 * The handler is run at a moment when nothing about the global state of the
114 * program is known. Therefore it cannot use facilities that manipulate global
115 * variables or locks. In particular, it cannot use malloc(); use mmap()
116 * instead. It cannot use fopen(); use open() instead. Etc. All global
117 * variables that are accessed by the handler should be marked 'volatile'.
119 typedef void (*stackoverflow_handler_t
) (int emergency
, stackoverflow_context_t scp
);
122 * Installs a stack overflow handler.
123 * The extra_stack argument is a pointer to a pre-allocated area used as a
124 * stack for executing the handler. It typically comes from a static variable
125 * or from heap-allocated memoty; placing it on the main stack may fail on
126 * some operating systems.
127 * Its size, passed in extra_stack_size, should be sufficiently large. The
128 * following code determines an appropriate size:
129 * #include <signal.h>
130 * #ifndef SIGSTKSZ / * glibc defines SIGSTKSZ for this purpose * /
131 * # define SIGSTKSZ 16384 / * on most platforms, 16 KB are sufficient * /
133 * Returns 0 on success, or -1 if the system doesn't support catching stack
136 extern int stackoverflow_install_handler (stackoverflow_handler_t handler
,
137 void* extra_stack
, unsigned long extra_stack_size
);
140 * Deinstalls the stack overflow handler.
142 extern void stackoverflow_deinstall_handler (void);
144 /* -------------------------------------------------------------------------- */
147 * The following structure and functions permit to define different SIGSEGV
148 * policies on different address ranges.
152 * The type of a local SIGSEGV handler.
153 * The fault address is passed as argument.
154 * The second argument is fixed arbitrary user data.
155 * The return value should be nonzero if the handler has done its job
156 * and no other handler should be called, or 0 if the handler declines
157 * responsibility for the given address.
159 typedef int (*sigsegv_area_handler_t
) (void* fault_address
, void* user_arg
);
162 * This structure represents a table of memory areas (address range intervals),
163 * with an local SIGSEGV handler for each.
166 struct sigsegv_dispatcher
{
172 * Initializes a sigsegv_dispatcher structure.
174 extern void sigsegv_init (sigsegv_dispatcher
* dispatcher
);
177 * Adds a local SIGSEGV handler to a sigsegv_dispatcher structure.
178 * It will cover the interval [address..address+len-1].
179 * Returns a "ticket" that can be used to remove the handler later.
181 extern void* sigsegv_register (sigsegv_dispatcher
* dispatcher
,
182 void* address
, unsigned long len
,
183 sigsegv_area_handler_t handler
, void* handler_arg
);
186 * Removes a local SIGSEGV handler.
188 extern void sigsegv_unregister (sigsegv_dispatcher
* dispatcher
, void* ticket
);
191 * Call the local SIGSEGV handler responsible for the given fault address.
192 * Return the handler's return value. 0 means that no handler has been found,
193 * or that a handler was found but declined responsibility.
195 extern int sigsegv_dispatch (sigsegv_dispatcher
* dispatcher
, void* fault_address
);
197 /* -------------------------------------------------------------------------- */
203 #endif /* _SIGSEGV_H */