=head1	NAME

dksignal - portable signal handling

=head1	SYNOPSIS

  #include <dksignal.h>

  dk_signal_ret_t my_handler(int signo)
  {
    dksignal_refresh(signo, handler);
    /* ... real signal processing ... */
  }

  typedef dk_signal_ret_t dk_signal_fct_t(int signo);

  typedef dk_signal_fct_t *dk_signal_disp_t;

  int dksignal_available(void);

  dk_signal_disp_t dksignal_set(int signo, dk_signal_disp_t newfct);

=head1	DESCRIPTION

On Unix there are different signal handling mechanisms available:

=over	4

=item	* signal()

Primitive signal handling. This mechanism has two drawback:

=over	8

=item	+ Arrival of a new signal while a signal handler is running
interrupts the signal handler.

=item	+ Before the signal handler is activated, the signal disposition
is set to the default. The signal handler must re-activate itself in order
to receive the same signal again. Even if the signal handler re-activates
itself as first instruction there is a little timing window in which
signals are not caught properly.

=back

=item	* sigset()

The sigset() mechanism installs permanent signal handlers, so there
is no such race condition as shown for the signal() mechanism.
If another signal arrives while a signal handler is running, the
running signal handler is finished before running the signal handler for the
next signal.

=item	* POSIX signal handling

A yet more powerfull mechanism to handle signals.

=back

Portable source code must be able to use all three mechanisms, programs
should issue a warning if the signal() mechanism is used.

If possible the dksignal module uses sigset() or POSIX sigaction(),
if none of this is available signal() is used.

The my_handler() function is an example for a signal handler function.

The dksignal_refres() macro re-activates the signal handler if the
signal() mechanism is in use. If sigset() or sigaction() is used
the macro does nothing.

The I<dk_signal_ret_t> is the return type of signal handlers, this
is either I<void> or I<int>.

The I<dk_signal_fct_t> is the function type for signal handlers.

The I<dk_signal_disp_t> is a type to store pointers to signal handler
functions.

The dksignal_set() function establishes a new signal handler for the
given signal number. A pointer to the old signal disposition is returned.
This can be used to re-establish the old signal disposition before
exiting the program.

The dksignal_available() function shows which signal processing
mechanism is in use. It returns 0 for signal() (the program should
issue a warning in this case), 1 for sigset() and 2 for sigaction().

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2001-2008, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
