[image of the Head of a GNU]

GNU libsigsegv - Handling page faults in user mode

  1. What is libsigsegv?
  2. Installation
  3. Copyright notice
  4. Download
  5. Developers

What is libsigsegv?

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:

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:

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: 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 instructions on Unix

        ./configure [OPTIONS]
        make check
        make install

Installation instructions on Woe32

See README.woe32.

Using libsigsegv in your package

Copyright notice

Copyright 1998-1999, 2002-2011 Bruno Haible
Copyright 2002-2005, 2009 Paolo Bonzini
Copyright 2008-2010 Eric Blake

This is free software distributed under the GNU General Public Licence described in the file COPYING. There is ABSOLUTELY NO WARRANTY, explicit or implied, on this software.


libsigsegv can be found on in the subdirectory /pub/gnu/libsigsegv/ on your favorite GNU mirror. For other ways to obtain libsigsegv, please read How to get GNU Software.

The latest release is
http://ftpmirror.gnu.org/libsigsegv/libsigsegv-2.10.tar.gz http://ftp.gnu.org/gnu/libsigsegv/libsigsegv-2.10.tar.gz

The latest development sources can be obtained through the savannah project.

Currently active developers:
Bruno Haible http://www.haible.de/bruno/
Paolo Bonzini http://www.inf.unisi.ch/~bonzini/
Eric Blake

Bug reports

Bug reports should be sent to <bug-libsigsegv-antispam@antispam.gnu.org>.
Return to GNU's home page.

Please send general FSF & GNU inquiries to <gnu@gnu.org>. There are also other ways to contact the FSF.
Please send broken links and other corrections or suggestions to <bug-libsigsegv-antispam@antispam.gnu.org>.

Copyright (C) 1998, 2010 Free Software Foundation, Inc.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Last updated: $Date: 2011/04/03 16:05:00 $ $Author: haible $