1 GNU libsigsegv - Handling page faults in user mode 2 3This is a library for handling page faults in user mode. A page fault 4occurs when a program tries to access to a region of memory that is 5currently not available. Catching and handling a page fault is a useful 6technique for implementing: 7 8 - pageable virtual memory, 9 - memory-mapped access to persistent databases, 10 - generational garbage collectors, 11 - stack overflow handlers, 12 - distributed shared memory, 13 - ... 14 15This library supports three sets of functions, all defined in <sigsegv.h>: 16 17 - Global SIGSEGV handlers: 18 sigsegv_install_handler, sigsegv_deinstall_handler. 19 20 - Local SIGSEGV handlers (a handler per memory area): 21 sigsegv_init, sigsegv_register, sigsegv_unregister, sigsegv_dispatch. 22 23 - Stack overflow handlers: 24 stackoverflow_install_handler, stackoverflow_deinstall_handler. 25 26Each of the three APIs can be used independently or simultaneously. 27For examples of the use of the APIs, see: 28 29 - Global SIGSEGV handlers: see tests/sigsegv1.c. 30 - Local SIGSEGV handlers: see tests/sigsegv2.c. 31 - Stack overflow handlers: see tests/stackoverflow1.c. 32 33 34About portability. 35 36Some platforms don't support this functionality. In <sigsegv.h>, the 37preprocessor macro HAVE_SIGSEGV_RECOVERY will be defined if global and 38local SIGSEGV handlers are available, and the preprocessor macro 39HAVE_STACK_OVERFLOW_RECOVERY will be defined if stack overflow handlers 40are available. Note that the declared functions are available in all cases; 41on platforms where HAVE_SIGSEGV_RECOVERY or HAVE_STACK_OVERFLOW_RECOVERY is 42not defined, they will simply always return an error code or do nothing. 43 44The list of platforms where this library is known to work is contained in 45the file PORTING. 46 47 48About pageable virtual memory. 49 50Pageable virtual memory is usually done in the operating system's kernel. 51This library helps in implementing the others. 52 53Installing a page fault handler is usually more efficient than doing 54access checks in software at every access, because it's effectively the 55hardware (the MMU) which checks whether a page is present or not. 56 57Note that if you use system calls (like read()) to write into write- 58protected pages, the system will react by returning -1 and setting 59errno to EFAULT, instead of signalling SIGSEGV and restarting the system 60call. In this case, the program has to do what the SIGSEGV handler would 61do, and then restart the read() operation. Some buggy systems (SunOS 4) 62go into an endless loop on this occasion; on these systems you have to 63make sure that an area is writable _before_ you call read() on it, 64 65 66About stack overflow handlers. 67 68In some applications, the stack overflow handler performs some cleanup or 69notifies the user and then immediately terminates the application. In 70other applications, the stack overflow handler longjmps back to a central 71point in the application. This library supports both uses. In the second 72case, the handler must ensure to restore the normal signal mask (because 73many signals are blocked while the handler is executed), and must also 74call sigsegv_leave_handler() to transfer control; then only it can longjmp 75away. 76 77Note that longjmping back to a central point in the application can leave 78the application in an inconsistent state, because 79 1) no cleanup is executed for call frames that are being unwound, 80 2) the code being executed while the stack overflow occurred might leave 81 data structures in an intermediate, inconsistent state. 82If you want to avoid the first problem, you need to restructure your 83application into three or more threads: 84 - a main thread, which creates the other threads, 85 - worker threads, which may cause stack overflows, and in which all 86 cleanups are registered through the pthread_cleanup_push function, 87 - a handler thread, which contains the handler for stack overflow and 88 other kinds of SIGSEGV. The handler will call pthread_cancel on the 89 worker thread whose stack overflowed. 90You will need to use the function pthread_sigmask on all threads except 91the handler thread, in order to ensure that the SIGSEGV signal gets handled 92in the designated handler thread. 93If you want to avoid the second problem together with the first problem, 94you need to enclose code that manipulates data structures in a way that is 95not safe to be interrupted within calls to pthread_setcancelstate() or 96pthread_setcanceltype(). 97If you want to avoid just the second problem, you need to manipulate all data 98structures in a way that is safe to be interrupted at any moment and also 99compile your program with the gcc flag -fnon-call-exceptions. 100 101 102About shared libraries. 103 104This library builds as a static library by default. This seems useful 105because of the small size of the library (4 KB). Of course, you can build 106it as a shared library by specifying the configure option '--enable-shared'. 107 108 109Installation 110------------ 111 112Installation instructions on Unix: 113 114 ./configure [OPTIONS] 115 make 116 make check 117 make install 118 119Installation instructions on Microsoft Windows: 120 121 See README.windows. 122 123 124Using libsigsegv in your package: 125 - For the APIs, see the comments in the <sigsegv.h> file (generated from 126 src/sigsegv.h.in). 127 - An autoconf macro for determining where libsigsegv is installed and how to 128 link with it is part of GNU gnulib, see 129 <https://www.gnu.org/software/gnulib/MODULES.html#module=libsigsegv> 130 131 132Copyright notice 133---------------- 134 135Copyright 1998-1999, 2002-2012, 2016-2018 Bruno Haible <bruno@clisp.org> 136Copyright 2002-2005, 2009 Paolo Bonzini <bonzini@gnu.org> 137Copyright 2008-2010 Eric Blake <ebb9@byu.net> 138 139This is free software distributed under the GNU General Public Licence v2 140described in the file COPYING or (at your option) any later version. 141There is ABSOLUTELY NO WARRANTY, explicit or implied, on this software. 142 143 144Download 145-------- 146 147 https://ftp.gnu.org/gnu/libsigsegv/libsigsegv-2.12.tar.gz 148 149Homepage 150-------- 151 152 https://www.gnu.org/software/libsigsegv/ 153 https://savannah.gnu.org/projects/libsigsegv 154 http://libsigsegv.sourceforge.net/ (old) 155 156Bug reports to 157-------------- 158 159 <bug-libsigsegv@gnu.org> 160