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