src/sigsegv.h.in

   1 /* Page fault handling library.
   2    Copyright (C) 1998-1999, 2002, 2004-2011  Bruno Haible <bruno@clisp.org>
   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, or (at your option)
   7    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, write to the Free Software Foundation,
  16    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
  17
  18 #ifndef _SIGSEGV_H
  19 #define _SIGSEGV_H
  20
  21 @FAULT_CONTEXT_INCLUDE@
  22
  23 /* HAVE_SIGSEGV_RECOVERY
  24    is defined if the system supports catching SIGSEGV.  */
  25 #if @HAVE_SIGSEGV_RECOVERY@
  26 # define HAVE_SIGSEGV_RECOVERY 1
  27 #endif
  28
  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
  33 #endif
  34
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 #define LIBSIGSEGV_VERSION 0x020A    /* version number: (major<<8) + minor */
  41 extern int libsigsegv_version;       /* Likewise */
  42
  43 /* -------------------------------------------------------------------------- */
  44
  45 /*
  46  * The mask of bits that are set to zero in a fault address that gets passed
  47  * to a global SIGSEGV handler.
  48  * On some platforms, the precise fault address is not known, only the memory
  49  * page into which the fault address falls. On these platforms,
  50  * SIGSEGV_FAULT_ADDRESS_ALIGNMENT is greater than 1.
  51  */
  52 #if defined __linux__ && (defined __s390__ || defined __s390x__)
  53 # define SIGSEGV_FAULT_ADDRESS_ALIGNMENT 0x1000UL
  54 #else
  55 # define SIGSEGV_FAULT_ADDRESS_ALIGNMENT 1UL
  56 #endif
  57
  58 /*
  59  * The type of a global SIGSEGV handler.
  60  * The fault address, with the bits (SIGSEGV_FAULT_ADDRESS_ALIGNMENT - 1)
  61  * cleared, is passed as argument.
  62  * The access type (read access or write access) is not passed; your handler
  63  * has to know itself how to distinguish these two cases.
  64  * The second argument is 0, meaning it could also be a stack overflow, or 1,
  65  * meaning the handler should seriously try to fix the fault.
  66  * The return value should be nonzero if the handler has done its job
  67  * and no other handler should be called, or 0 if the handler declines
  68  * responsibility for the given address.
  69  *
  70  * The handler is run at a moment when nothing about the global state of the
  71  * program is known. Therefore it cannot use facilities that manipulate global
  72  * variables or locks. In particular, it cannot use malloc(); use mmap()
  73  * instead. It cannot use fopen(); use open() instead. Etc. All global
  74  * variables that are accessed by the handler should be marked 'volatile'.
  75  */
  76 typedef int (*sigsegv_handler_t) (void* fault_address, int serious);
  77
  78 /*
  79  * Installs a global SIGSEGV handler.
  80  * This should be called once only, and it ignores any previously installed
  81  * SIGSEGV handler.
  82  * Returns 0 on success, or -1 if the system doesn't support catching SIGSEGV.
  83  */
  84 extern int sigsegv_install_handler (sigsegv_handler_t handler);
  85
  86 /*
  87  * Deinstalls the global SIGSEGV handler.
  88  * This goes back to the state where no SIGSEGV handler is installed.
  89  */
  90 extern void sigsegv_deinstall_handler (void);
  91
  92 #if LIBSIGSEGV_VERSION >= 0x0206
  93 /*
  94  * Prepares leaving a SIGSEGV handler (through longjmp or similar means).
  95  * Control is transferred by calling CONTINUATION with CONT_ARG1, CONT_ARG2,
  96  * CONT_ARG3 as arguments.
  97  * CONTINUATION must not return.
  98  * The sigsegv_leave_handler function may return if called from a SIGSEGV
  99  * handler; its return value should be used as the handler's return value.
 100  * The sigsegv_leave_handler function does not return if called from a
 101  * stack overflow handler.
 102  */
 103 extern int sigsegv_leave_handler (void (*continuation) (void*, void*, void*), void* cont_arg1, void* cont_arg2, void* cont_arg3);
 104 #else /* older versions of libsigsegv */
 105 /*
 106  * Prepares leaving a SIGSEGV handler (through longjmp or similar means).
 107  * Limitation: This function could only be called once on MacOS X.
 108  */
 109 extern void sigsegv_leave_handler (void);
 110 #endif
 111
 112 /*
 113  * The type of a context passed to a stack overflow handler.
 114  * This type is system dependent; on some platforms it is an 'ucontext_t *',
 115  * on some platforms it is a 'struct sigcontext *', on others merely an
 116  * opaque 'void *'.
 117  */
 118 typedef @FAULT_CONTEXT@ *stackoverflow_context_t;
 119
 120 /*
 121  * The type of a stack overflow handler.
 122  * Such a handler should perform a longjmp call in order to reduce the amount
 123  * of stack needed. It must not return.
 124  * The emergency argument is 0 when the stack could be repared, or 1 if the
 125  * application should better save its state and exit now.
 126  *
 127  * The handler is run at a moment when nothing about the global state of the
 128  * program is known. Therefore it cannot use facilities that manipulate global
 129  * variables or locks. In particular, it cannot use malloc(); use mmap()
 130  * instead. It cannot use fopen(); use open() instead. Etc. All global
 131  * variables that are accessed by the handler should be marked 'volatile'.
 132  */
 133 typedef void (*stackoverflow_handler_t) (int emergency, stackoverflow_context_t scp);
 134
 135 /*
 136  * Installs a stack overflow handler.
 137  * The extra_stack argument is a pointer to a pre-allocated area used as a
 138  * stack for executing the handler. It typically comes from a static variable
 139  * or from heap-allocated memoty; placing it on the main stack may fail on
 140  * some operating systems.
 141  * Its size, passed in extra_stack_size, should be sufficiently large.  The
 142  * following code determines an appropriate size:
 143  *   #include <signal.h>
 144  *   #ifndef SIGSTKSZ         / * glibc defines SIGSTKSZ for this purpose * /
 145  *   # define SIGSTKSZ 16384  / * on most platforms, 16 KB are sufficient * /
 146  *   #endif
 147  * Returns 0 on success, or -1 if the system doesn't support catching stack
 148  * overflow.
 149  */
 150 extern int stackoverflow_install_handler (stackoverflow_handler_t handler,
 151                                           void* extra_stack, unsigned long extra_stack_size);
 152
 153 /*
 154  * Deinstalls the stack overflow handler.
 155  */
 156 extern void stackoverflow_deinstall_handler (void);
 157
 158 /* -------------------------------------------------------------------------- */
 159
 160 /*
 161  * The following structure and functions permit to define different SIGSEGV
 162  * policies on different address ranges.
 163  */
 164
 165 /*
 166  * The type of a local SIGSEGV handler.
 167  * The fault address is passed as argument.
 168  * The second argument is fixed arbitrary user data.
 169  * The return value should be nonzero if the handler has done its job
 170  * and no other handler should be called, or 0 if the handler declines
 171  * responsibility for the given address.
 172  */
 173 typedef int (*sigsegv_area_handler_t) (void* fault_address, void* user_arg);
 174
 175 /*
 176  * This structure represents a table of memory areas (address range intervals),
 177  * with an local SIGSEGV handler for each.
 178  */
 179 typedef
 180 struct sigsegv_dispatcher {
 181   void* tree;
 182 }
 183 sigsegv_dispatcher;
 184
 185 /*
 186  * Initializes a sigsegv_dispatcher structure.
 187  */
 188 extern void sigsegv_init (sigsegv_dispatcher* dispatcher);
 189
 190 /*
 191  * Adds a local SIGSEGV handler to a sigsegv_dispatcher structure.
 192  * It will cover the interval [address..address+len-1].
 193  * The address and len arguments must be multiples of
 194  * SIGSEGV_FAULT_ADDRESS_ALIGNMENT.
 195  * Returns a "ticket" that can be used to remove the handler later.
 196  */
 197 extern void* sigsegv_register (sigsegv_dispatcher* dispatcher,
 198                                void* address, unsigned long len,
 199                                sigsegv_area_handler_t handler, void* handler_arg);
 200
 201 /*
 202  * Removes a local SIGSEGV handler.
 203  */
 204 extern void sigsegv_unregister (sigsegv_dispatcher* dispatcher, void* ticket);
 205
 206 /*
 207  * Call the local SIGSEGV handler responsible for the given fault address.
 208  * Return the handler's return value. 0 means that no handler has been found,
 209  * or that a handler was found but declined responsibility.
 210  */
 211 extern int sigsegv_dispatch (sigsegv_dispatcher* dispatcher, void* fault_address);
 212
 213 /* -------------------------------------------------------------------------- */
 214
 215 #ifdef __cplusplus
 216 }
 217 #endif
 218
 219 #endif /* _SIGSEGV_H */