/*
    Copyright (C) 2008 Andreas Baumann <abaumann@yahoo.com>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef WOLF_SIGNALS_H
#define WOLF_SIGNALS_H

/**
 * @addtogroup wolf_unix Unix-specific
 * @{
 */

/**
 * @addtogroup wolf_signals Signal Handling
 * @{
 */

/**
 * @file signals.h
 * @brief Unix Signal Handling
 * @author Andreas Baumann <abaumann@yahoo.com>
 */

#include "errors.h"

#include <stdarg.h>			/* for variable arguments */
#include <signal.h>			/* for signal constants,
					   sigaction, kill, etc. */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Retrieve the short name for a signal number.
 *
 * @param sig        the signal number as defined in signal.h
 * @return           the short name of the signal, e. g.
 *                   "SIGFPE", or NULL if the signal is unknown
 *                   on this platform
 */
const char *wolf_signal_get_short_name( int sig );

/**
 * Retrieve the human-readable name for a signal number.
 *
 * @param sig        the signal number as defined in signal.h
 * @return           the long name of the signal, e. g. for
 *                   SIGFPE you get "Floating-point exception",
 *                   or NULL if the signal is unknown on this
 *                   platform
 */
const char *wolf_signal_get_long_name( int sig );

/**
 * Installs a signal handler to ignore the signal completly. For
 * some signals like SIGPIPE or SIGC(H)LD this also changes the
 * behaviour how functions like write or waitpid are working, so it's
 * better to use wolf_signal_install_empty for those signals.
 *
 * Other signals like SIGKILL can't be ignored at all.
 *
 * @param sig       pass an arbitrary number of signal numbers
 *                  to terminate the enumeration, pass a 0
 * @return          WOLF_OK if the signal will be ignored,
 *                  WOLF_PROGRAMMING if the signal can't be
 *                  ignored.
 */
wolf_error_t wolf_signal_install_ignore( int sig, ... );

/**
 * Installs a signal handler doing nothing. This is better than
 * wolf_signal_install_ignore for signals like SIGPIPE or SIGC(H)LD.
 *
 * @param sig       pass an arbitrary number of signal numbers
 *                  to terminate the enumeration, pass a 0
 * @return          WOLF_OK if the empty signal handler could be
 *                  installed,
 *                  WOLF_PROGRAMMING if the handler could not be
 *                  installed
 */
wolf_error_t wolf_signal_install_empty( int sig, ... );

/**
 * @brief a signal handler function
 */
typedef void (*wolf_signal_func_t)( int );

/**
 * Install an arbitrary function as signal handler.
 *
 * @param func      the signal handler to install
 * @param sig       pass an arbitrary number of signal numbers
 *                  to terminate the enumeration, pass a 0
 * @return          WOLF_OK if the signal handler could be
 *                  installed,
 *                  WOLF_PROGRAMMING if the handler could not be
 *                  installed
 */
wolf_error_t wolf_signal_install_func( wolf_signal_func_t func, int sig, ... );

/**
 * Install an arbitrary function as signal handler. You should usually
 * call wolf_signal_install_func, not this function.
 *
 * @param func      the signal handler to install
 * @param sig       the first signal number to install
 * @param ap        the list from the second signal handler to
 *                  the terminating 0 of a signal handler list
 * @return          WOLF_OK if the signal handler could be
 *                  installed,
 *                  WOLF_PROGRAMMING if the handler could not be
 *                  installed
 */
wolf_error_t vsignal_install_func( wolf_signal_func_t func, int sig, va_list ap );

/**
 * Macros generating the wrapper to wrap a function taking a list of signals
 * and mapping it to the function call taking a single signal and a
 * va_list.
 */
#define WOLF_SIGNALS_INSTALL_FUNC( MODE, FUNC ) \
wolf_error_t wolf_signal_install_##MODE( int sig, ... ) { \
	va_list ap; \
	wolf_error_t error; \
	va_start( ap, sig ); \
	error = vsignal_install_func( FUNC, sig, ap ); \
	va_end( ap ); \
	return error; \
}

/**
 * Install a fatal signal handler. It prints a fatal log message and
 * the calls the default behaviour of the signal.
 *
 * @param sig       pass an arbitrary number of signal numbers
 *                  to terminate the enumeration, pass a 0
 * @return          WOLF_OK if the signal handler could be
 *                  installed,
 *                  WOLF_PROGRAMMING if the handler could not be
 *                  installed
 */
wolf_error_t wolf_signal_install_fatal( int sig, ... );

#ifdef __cplusplus
}
#endif

/** @} */ /* @addtogroup wolf_signals */

/** @} */ /* @addtogroup wolf_unix */

#endif /* ifndef WOLF_SIGNALS_H */