File Explorer

1           GNU libsigsegv  -  Handling page faults in user mode2 3This is a library for handling page faults in user mode. A page fault4occurs when a program tries to access to a region of memory that is5currently not available. Catching and handling a page fault is a useful6technique 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>, the37preprocessor macro HAVE_SIGSEGV_RECOVERY will be defined if global and38local SIGSEGV handlers are available, and the preprocessor macro39HAVE_STACK_OVERFLOW_RECOVERY will be defined if stack overflow handlers40are available. Note that the declared functions are available in all cases;41on platforms where HAVE_SIGSEGV_RECOVERY or HAVE_STACK_OVERFLOW_RECOVERY is42not 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 in45the 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 doing54access checks in software at every access, because it's effectively the55hardware (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 setting59errno to EFAULT, instead of signalling SIGSEGV and restarting the system60call. In this case, the program has to do what the SIGSEGV handler would61do, and then restart the read() operation. Some buggy systems (SunOS 4)62go into an endless loop on this occasion; on these systems you have to63make 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 or69notifies the user and then immediately terminates the application.  In70other applications, the stack overflow handler longjmps back to a central71point in the application.  This library supports both uses.  In the second72case, the handler must ensure to restore the normal signal mask (because73many signals are blocked while the handler is executed), and must also74call sigsegv_leave_handler() to transfer control; then only it can longjmp75away.76 77Note that longjmping back to a central point in the application can leave78the application in an inconsistent state, because79  1) no cleanup is executed for call frames that are being unwound,80  2) the code being executed while the stack overflow occurred might leave81     data structures in an intermediate, inconsistent state.82If you want to avoid the first problem, you need to restructure your83application 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 all86    cleanups are registered through the pthread_cleanup_push function,87  - a handler thread, which contains the handler for stack overflow and88    other kinds of SIGSEGV. The handler will call pthread_cancel on the89    worker thread whose stack overflowed.90You will need to use the function pthread_sigmask on all threads except91the handler thread, in order to ensure that the SIGSEGV signal gets handled92in 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 is95not safe to be interrupted within calls to pthread_setcancelstate() or96pthread_setcanceltype().97If you want to avoid just the second problem, you need to manipulate all data98structures in a way that is safe to be interrupted at any moment and also99compile 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 useful105because of the small size of the library (4 KB).  Of course, you can build106it as a shared library by specifying the configure option '--enable-shared'.107 108 109Installation110------------111 112Installation instructions on Unix:113 114        ./configure [OPTIONS]115        make116        make check117        make install118 119Installation instructions on Microsoft Windows:120 121        See INSTALL.windows.122 123 124Using libsigsegv in your package:125  - For the APIs, see the comments in the <sigsegv.h> file (generated from126    src/sigsegv.h.in).127  - An autoconf macro for determining where libsigsegv is installed and how to128    link with it is part of GNU gnulib, see129    <https://www.gnu.org/software/gnulib/MODULES.html#module=libsigsegv>130 131 132Copyright notice133----------------134 135Copyright 1998-1999, 2002-2012, 2016-2021  Bruno Haible <bruno@clisp.org>136Copyright 2002-2005, 2009  Paolo Bonzini <bonzini@gnu.org>137Copyright 2008-2010  Eric Blake <ebb9@byu.net>138Copyright 2002-2021  Free Software Foundation, Inc.139 140This is free software distributed under the GNU General Public Licence v2141described in the file COPYING or (at your option) any later version.142There is ABSOLUTELY NO WARRANTY, explicit or implied, on this software.143 144 145Download146--------147 148    https://ftp.gnu.org/gnu/libsigsegv/libsigsegv-2.13.tar.gz149 150Homepage151--------152 153    https://www.gnu.org/software/libsigsegv/154    https://savannah.gnu.org/projects/libsigsegv155    http://libsigsegv.sourceforge.net/ (old)156 157Bug reports158-----------159 160Report bugs161  - in the bug tracker at <https://savannah.gnu.org/projects/libsigsegv>162  - or by email to <bug-libsigsegv@gnu.org>.163