GNU libsigsegv  -  Handling page faults in user mode

This is a library for handling page faults in user mode. A page fault
occurs when a program tries to access to a region of memory that is
currently not available. Catching and handling a page fault is a useful
technique for implementing:

  - pageable virtual memory,
  - memory-mapped access to persistent databases,
  - generational garbage collectors,
  - stack overflow handlers,
  - distributed shared memory,
  - ...

This library supports three sets of functions, all defined in <sigsegv.h>:

  - Global SIGSEGV handlers:
    sigsegv_install_handler, sigsegv_deinstall_handler.

  - Local SIGSEGV handlers (a handler per memory area):
    sigsegv_init, sigsegv_register, sigsegv_unregister, sigsegv_dispatch.

  - Stack overflow handlers:
    stackoverflow_install_handler, stackoverflow_deinstall_handler.

Each of the three APIs can be used independently or simultaneously.
For examples of the use of the APIs, see:

  - Global SIGSEGV handlers: see tests/sigsegv1.c.
  - Local SIGSEGV handlers: see tests/sigsegv2.c.
  - Stack overflow handlers: see tests/stackoverflow1.c.


About portability.

Some platforms don't support this functionality. In <sigsegv.h>, the
preprocessor macro HAVE_SIGSEGV_RECOVERY will be defined if global and
local SIGSEGV handlers are available, and the preprocessor macro
HAVE_STACK_OVERFLOW_RECOVERY will be defined if stack overflow handlers
are available. Note that the declared functions are available in all cases;
on platforms where HAVE_SIGSEGV_RECOVERY or HAVE_STACK_OVERFLOW_RECOVERY is
not defined, they will simply always return an error code or do nothing.

The list of platforms where this library is known to work is contained in
the file PORTING.


About pageable virtual memory.

Pageable virtual memory is usually done in the operating system's kernel.
This library helps in implementing the others.

Installing a page fault handler is usually more efficient than doing
access checks in software at every access, because it's effectively the
hardware (the MMU) which checks whether a page is present or not.

Note that if you use system calls (like read()) to write into write-
protected pages, the system will react by returning -1 and setting
errno to EFAULT, instead of signalling SIGSEGV and restarting the system
call. In this case, the program has to do what the SIGSEGV handler would
do, and then restart the read() operation. Some buggy systems (SunOS 4)
go into an endless loop on this occasion; on these systems you have to
make sure that an area is writable _before_ you call read() on it,


About stack overflow handlers.

In some applications, the stack overflow handler performs some cleanup or
notifies the user and then immediately terminates the application.  In
other applications, the stack overflow handler longjmps back to a central
point in the application.  This library supports both uses.  In the second
case, the handler must ensure to restore the normal signal mask (because
many signals are blocked while the handler is executed), and must also
call sigsegv_leave_handler() to transfer control; then only it can longjmp
away.

Note that longjmping back to a central point in the application can leave
the application in an inconsistent state, because
  1) no cleanup is executed for call frames that are being unwound,
  2) the code being executed while the stack overflow occurred might leave
     data structures in an intermediate, inconsistent state.
If you want to avoid the first problem, you need to restructure your
application into three or more threads:
  - a main thread, which creates the other threads,
  - worker threads, which may cause stack overflows, and in which all
    cleanups are registered through the pthread_cleanup_push function,
  - a handler thread, which contains the handler for stack overflow and
    other kinds of SIGSEGV. The handler will call pthread_cancel on the
    worker thread whose stack overflowed.
You will need to use the function pthread_sigmask on all threads except
the handler thread, in order to ensure that the SIGSEGV signal gets handled
in the designated handler thread.
If you want to avoid the second problem together with the first problem,
you need to enclose code that manipulates data structures in a way that is
not safe to be interrupted within calls to pthread_setcancelstate() or
pthread_setcanceltype().
If you want to avoid just the second problem, you need to manipulate all data
structures in a way that is safe to be interrupted at any moment and also
compile your program with the gcc flag -fnon-call-exceptions.


About shared libraries.

This library builds as a static library by default.  This seems useful
because of the small size of the library (4 KB).  Of course, you can build
it as a shared library by specifying the configure option '--enable-shared'.


Installation
------------

Installation instructions on Unix:

        ./configure [OPTIONS]
        make
        make check
        make install

Installation instructions on Microsoft Windows:

        See README.windows.


Using libsigsegv in your package:
  - For the APIs, see the comments in the <sigsegv.h> file (generated from
    src/sigsegv.h.in).
  - An autoconf macro for determining where libsigsegv is installed and how to
    link with it is part of GNU gnulib, see
    <https://www.gnu.org/software/gnulib/MODULES.html#module=libsigsegv>


Copyright notice
----------------

Copyright 1998-1999, 2002-2012, 2016-2018  Bruno Haible <bruno@clisp.org>
Copyright 2002-2005, 2009  Paolo Bonzini <bonzini@gnu.org>
Copyright 2008-2010  Eric Blake <ebb9@byu.net>

This is free software distributed under the GNU General Public Licence v2
described in the file COPYING or (at your option) any later version.
There is ABSOLUTELY NO WARRANTY, explicit or implied, on this software.


Download
--------

    https://ftp.gnu.org/gnu/libsigsegv/libsigsegv-2.12.tar.gz

Homepage
--------

    https://www.gnu.org/software/libsigsegv/
    https://savannah.gnu.org/projects/libsigsegv
    http://libsigsegv.sourceforge.net/ (old)

Bug reports to
--------------

    <bug-libsigsegv@gnu.org>

Installation on Microsoft Windows:

There are three ways to create binaries of this package for Microsoft Windows:
1) Native binaries, built using the mingw tool chain.
2) Native binaries, built using the MS Visual C/C++ tool chain.
3) Binaries for the Cygwin environment.

===============================================================================
1) Native binaries, built using the mingw tool chain.

   I recommend to use the Cygwin environment as the development environment
   and mingw only as the target (runtime, deployment) environment.
   For this, you need to install
     * Cygwin (from https://cygwin.com/),
     * some packages available from the Cygwin package installer:
         make
     * the mingw cross-compilation tools and runtime package, available from
       the Cygwin package installer (setup-x86_64.exe):
       - for creating 32-bit binaries: packages
           mingw64-i686-gcc-core,
           mingw64-i686-headers,
           mingw64-i686-runtime
       - for creating 64-bit binaries: packages
           mingw64-x86_64-gcc-core,
           mingw64-x86_64-headers,
           mingw64-x86_64-runtime

   Building 32-bit binaries for mingw is achieved through the following
   preparation, configure, and build commands:

      PATH=/usr/local/mingw32/bin:$PATH
      export PATH
      ./configure --host=i686-w64-mingw32 --prefix=/usr/local/mingw32 \
            CC=i686-w64-mingw32-gcc \
            CPPFLAGS="-I/usr/local/mingw32/include -Wall" \
            LDFLAGS="-L/usr/local/mingw32/lib"
      make
      make check

   Building 64-bit binaries for mingw is achieved through the following
   preparation, configure, and build commands:

      PATH=/usr/local/mingw64/bin:$PATH
      export PATH
      ./configure --host=x86_64-w64-mingw32 --prefix=/usr/local/mingw64 \
            CC=x86_64-w64-mingw32-gcc \
            CPPFLAGS="-I/usr/local/mingw64/include -Wall" \
            LDFLAGS="-L/usr/local/mingw64/lib"
      make
      make check

   Installation:

      make install

===============================================================================
2) Native binaries, built using the MS Visual C/C++ tool chain.

   Note that binaries created with MSVC have a distribution constraint: They
   depend on a closed-source library ('msvcr90.dll' for MSVC 9.0,
   'vcruntime140.dll' for MSVC 14.0, and so on) which is not normally part of
   a Windows installation.
   You cannot distribute 'vcruntime*.dll' with the binaries - this would be a
   violation of the GPL and of the Microsoft EULA.
   You can distribute the binaries without including 'vcruntime*.dll'. Users
   who don't have this library on their system will require to pull some files
   (api-ms-win*.dll) through the Windows Update mechanism, see
   https://support.microsoft.com/en-us/kb/2999226 .

   This recipe requires MS Visual C/C++ 9.0 or newer.
   You don't need the Visual Studio IDE, just the C/C++ tool chain.
   As of 2016, you can install the MS Visual C/C++ 14.0 tool chain from
   http://landinghub.visualstudio.com/visual-cpp-build-tools (it's the file
   visualcppbuildtools_full.exe).

   This recipe requires also a Cygwin environment (with 'bash', the common POSIX
   commands, and 'make') as a build environment. Building with 'nmake' is not
   supported.
   For this, you need to install
     * Cygwin (from https://cygwin.com/),
     * some packages available from the Cygwin package installer:
         make

   You also need the scripts 'ar-lib' and 'compile' from
     http://git.savannah.gnu.org/gitweb/?p=automake.git;a=blob_plain;f=lib/ar-lib;hb=HEAD
     http://git.savannah.gnu.org/gitweb/?p=automake.git;a=blob_plain;f=lib/compile;hb=HEAD
   respectively.
   They may also be included in this package, in directory 'build-aux/'.
   Save them; the instructions below assume that you stored them in $HOME/msvc/.
   Make them executable:
      chmod a+x ar-lib compile

   Start a bash (from Cygwin).

   Make sure that the MSVC tools ("cl" etc.) are found in PATH and the
   environment variables INCLUDE and LIB are set appropriately.
   In a typical MSVC 9.0 installation, it can be achieved by running
     C:\Program Files\Microsoft Visual Studio 9.0\Common7\Tools\vsvars32.bat
   In a typical MSVC 14.0 installation on Windows 10, it can be achieved
   - for creating 32-bit binaries: through the following bash commands:

      # Set environment variables for using MSVC 14,
      # for creating native 32-bit Windows executables.

      # Windows C library headers and libraries.
      WindowsCrtIncludeDir='C:\Program Files (x86)\Windows Kits\10\Include\10.0.10240.0\ucrt'
      WindowsCrtLibDir='C:\Program Files (x86)\Windows Kits\10\Lib\10.0.10240.0\ucrt\'
      INCLUDE="${WindowsCrtIncludeDir};$INCLUDE"
      LIB="${WindowsCrtLibDir}x86;$LIB"

      # Windows API headers and libraries.
      WindowsSdkIncludeDir='C:\Program Files (x86)\Windows Kits\8.1\Include\'
      WindowsSdkLibDir='C:\Program Files (x86)\Windows Kits\8.1\Lib\winv6.3\um\'
      INCLUDE="${WindowsSdkIncludeDir}um;${WindowsSdkIncludeDir}shared;$INCLUDE"
      LIB="${WindowsSdkLibDir}x86;$LIB"

      # Visual C++ tools, headers and libraries.
      VSINSTALLDIR='C:\Program Files (x86)\Microsoft Visual Studio 14.0'
      VCINSTALLDIR="${VSINSTALLDIR}"'\VC'
      PATH=`cygpath -u "${VCINSTALLDIR}"`/bin:"$PATH"
      INCLUDE="${VCINSTALLDIR}"'\include;'"${INCLUDE}"
      LIB="${VCINSTALLDIR}"'\lib;'"${LIB}"

      export INCLUDE LIB

   - for creating 64-bit binaries: through the following bash commands:

     # Set environment variables for using MSVC 14,
     # for creating native 64-bit Windows executables.

     # Windows C library headers and libraries.
     WindowsCrtIncludeDir='C:\Program Files (x86)\Windows Kits\10\Include\10.0.10240.0\ucrt'
     WindowsCrtLibDir='C:\Program Files (x86)\Windows Kits\10\Lib\10.0.10240.0\ucrt\'
     INCLUDE="${WindowsCrtIncludeDir};$INCLUDE"
     LIB="${WindowsCrtLibDir}x64;$LIB"

     # Windows API headers and libraries.
     WindowsSdkIncludeDir='C:\Program Files (x86)\Windows Kits\8.1\Include\'
     WindowsSdkLibDir='C:\Program Files (x86)\Windows Kits\8.1\Lib\winv6.3\um\'
     INCLUDE="${WindowsSdkIncludeDir}um;${WindowsSdkIncludeDir}shared;$INCLUDE"
     LIB="${WindowsSdkLibDir}x64;$LIB"

     # Visual C++ tools, headers and libraries.
     VSINSTALLDIR='C:\Program Files (x86)\Microsoft Visual Studio 14.0'
     VCINSTALLDIR="${VSINSTALLDIR}"'\VC'
     PATH=`cygpath -u "${VCINSTALLDIR}"`/bin/amd64:"$PATH"
     INCLUDE="${VCINSTALLDIR}"'\include;'"${INCLUDE}"
     LIB="${VCINSTALLDIR}"'\lib\amd64;'"${LIB}"

     export INCLUDE LIB

   Building 32-bit binaries with MSVC is achieved through the following
   preparation, configure, and build commands:

      PATH=/usr/local/msvc32/bin:$PATH
      export PATH

      win32_target=_WIN32_WINNT_WINXP   # for MSVC 9.0
      win32_target=_WIN32_WINNT_VISTA   # possibly for MSVC >= 10.0
      win32_target=_WIN32_WINNT_WIN7    # possibly for MSVC >= 10.0
      win32_target=_WIN32_WINNT_WIN8    # possibly for MSVC >= 10.0

      ./configure --host=i686-w64-mingw32 --prefix=/usr/local/msvc32 \
            CC="$HOME/msvc/compile cl -nologo" \
            CFLAGS="-MD" \
            CXX="$HOME/msvc/compile cl -nologo" \
            CXXFLAGS="-MD" \
            CPPFLAGS="-D_WIN32_WINNT=$win32_target -I/usr/local/msvc32/include" \
            LDFLAGS="-L/usr/local/msvc32/lib" \
            LD="link" \
            NM="dumpbin -symbols" \
            STRIP=":" \
            AR="$HOME/msvc/ar-lib lib" \
            RANLIB=":"
      make
      make check

   Building 64-bit binaries with MSVC is achieved through the following
   preparation, configure, and build commands:

      PATH=/usr/local/msvc64/bin:$PATH
      export PATH

      win32_target=_WIN32_WINNT_WINXP   # for MSVC 9.0
      win32_target=_WIN32_WINNT_VISTA   # possibly for MSVC >= 10.0
      win32_target=_WIN32_WINNT_WIN7    # possibly for MSVC >= 10.0
      win32_target=_WIN32_WINNT_WIN8    # possibly for MSVC >= 10.0

      ./configure --host=x86_64-w64-mingw32 --prefix=/usr/local/msvc64 \
            CC="$HOME/msvc/compile cl -nologo" \
            CFLAGS="-MD" \
            CXX="$HOME/msvc/compile cl -nologo" \
            CXXFLAGS="-MD" \
            CPPFLAGS="-D_WIN32_WINNT=$win32_target -I/usr/local/msvc64/include" \
            LDFLAGS="-L/usr/local/msvc64/lib" \
            LD="link" \
            NM="dumpbin -symbols" \
            STRIP=":" \
            AR="$HOME/msvc/ar-lib lib" \
            RANLIB=":"
      make
      make check

   Installation:

      make install

===============================================================================
3) Binaries for the Cygwin environment.

   The generic instructions in the INSTALL file apply. But here are more
   specific ones.

   You need to install
     * Cygwin (from https://cygwin.com/),
     * some packages available from the Cygwin package installer:
         make
     * the Cygwin [cross-]compilation tools package, available from
       the Cygwin package installer (setup-x86_64.exe):
       - for creating 32-bit binaries: packages
           cygwin32-gcc-core,
           cygwin32
       - for creating 64-bit binaries: packages
           gcc-core

   Building 32-bit binaries for Cygwin must be done in a directory *outside*
   the Cygwin /home and /usr hierarchies. It is achieved through the following
   preparation, configure, and build commands:

      PATH=/usr/local/cygwin32/bin:/usr/i686-pc-cygwin/sys-root/usr/bin:$PATH
      export PATH
      ./configure --host=i686-pc-cygwin --prefix=/usr/local/cygwin32 \
            CC=i686-pc-cygwin-gcc \
            CPPFLAGS="-I/usr/local/cygwin32/include -Wall" \
            LDFLAGS="-L/usr/local/cygwin32/lib"
      make
      make check

   Building 64-bit binaries for Cygwin is achieved through the following
   preparation, configure, and build commands:

      PATH=/usr/local/cygwin64/bin:$PATH
      export PATH
      ./configure --host=x86_64-pc-cygwin --prefix=/usr/local/cygwin64 \
            CC=x86_64-pc-cygwin-gcc \
            CPPFLAGS="-I/usr/local/cygwin64/include -Wall" \
            LDFLAGS="-L/usr/local/cygwin64/lib"
      make
      make check

   Installation:

      make install

===============================================================================