README

   1            GNU libsigsegv  -  Handling page faults in user mode
   2
   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:
   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
  15 This 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
  26 Each of the three APIs can be used independently or simultaneously.
  27 For 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
  34 About portability.
  35
  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.
  43
  44 The list of platforms where this library is known to work is contained in
  45 the file PORTING.
  46
  47
  48 About pageable virtual memory.
  49
  50 Pageable virtual memory is usually done in the operating system's kernel.
  51 This library helps in implementing the others.
  52
  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.
  56
  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,
  64
  65
  66 About stack overflow handlers.
  67
  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.
  76
  77
  78 About shared libraries.
  79
  80 This library builds as a static library by default.  This seems useful
  81 because of the small size of the library (4 KB).  Of course, you can build
  82 it as a shared library by specifying the configure option '--enable-shared'.
  83
  84
  85 Installation instructions on Unix:
  86
  87         ./configure
  88         make
  89         make check
  90         make install
  91
  92 Installation instructions on Woe32:
  93
  94         See README.woe32.
  95
  96
  97 Using libsigsegv in your package:
  98   - For the APIs, see the comments in the <sigsegv.h> file (generated from
  99     src/sigsegv.h.in).
 100   - An autoconf macro for determining where libsigsegv is installed and how to
 101     link with it is part of GNU gnulib, see
 102     <http://www.gnu.org/software/gnulib/MODULES.html#module=libsigsegv>
 103
 104
 105 Copyright notice:
 106
 107 Copyright 1998-1999, 2002-2008  Bruno Haible <bruno@clisp.org>
 108 Copyright 2002-2005  Paolo Bonzini <bonzini@gnu.org>
 109 Copyright 2008  Eric Blake <ebb9@byu.net>
 110
 111 This is free software distributed under the GNU General Public Licence
 112 described in the file COPYING. There is ABSOLUTELY NO WARRANTY, explicit or
 113 implied, on this software.
 114
 115
 116 Download:
 117
 118 ftp://ftp.gnu.org/pub/gnu/libsigsegv/libsigsegv-2.6.tar.gz
 119 http://ftp.gnu.org/gnu/libsigsegv/libsigsegv-2.6.tar.gz
 120
 121 Homepage:
 122
 123 http://libsigsegv.sourceforge.net/