lib/sigsegv.in.h

   1 /* Page fault handling library.
   2    Copyright (C) 1998-2024 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  * <https://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 memory; 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 */