## POSIX Signal Handling

POSIX Signal Handling — a callback system for handling POSIX signals safely

## Synopsis

    #include <libxfce4util/libxfce4util.h>

    void                (*XfcePosixSignalHandler)           (gint signal,
                                                             gpointer user_data);
    gboolean            xfce_posix_signal_handler_init      (GError **error);
    void                xfce_posix_signal_handler_restore_handler
                                                            (gint signal);
    gboolean            xfce_posix_signal_handler_set_handler
                                                            (gint signal,
                                                             XfcePosixSignalHandler handler,
                                                             gpointer user_data,
                                                             GError **error);
    void                xfce_posix_signal_handler_shutdown  ();

## Description

Due to reentrancy issues, there is a restricted set of functions/syscalls that are allowed to be performed inside a POSIX signal handler. In general, it's safer to defer any signal-related processing until after the signal handler has run. The functionality in this module automatically handles this, and allows you to set a handler function (with optional user data) for any signal.

## Details

### XfcePosixSignalHandler ()

    void                (*XfcePosixSignalHandler)           (gint signal,
                                                             gpointer user_data);

A function signature to use for POSIX signal handler functions.

`signal` : | The signal that was caught.
`user_data` : | The `user_data` parameter passed when the handler was registered.

### xfce_posix_signal_handler_init ()

    gboolean            xfce_posix_signal_handler_init      (GError **error);

Initializes the POSIX signal handler system. Must be called before setting any POSIX signal handlers.

`error` : | Location of a GError to store any possible errors.
Returns : | `TRUE` on success, `FALSE` on failure, in which case `error` will be set.

### xfce_posix_signal_handler_restore_handler ()

    void                xfce_posix_signal_handler_restore_handler
                                                            (gint signal);

Restores the default handler for `signal`.

`signal` : | A POSIX signal id number.

### xfce_posix_signal_handler_set_handler ()

    gboolean            xfce_posix_signal_handler_set_handler
                                                            (gint signal,
                                                             XfcePosixSignalHandler handler,
                                                             gpointer user_data,
                                                             GError **error);

Sets `handler` to be called whenever `signal` is caught by the application. The `user_data` parameter will be passed as an argument to `handler`.

`signal` : | A POSIX signal id number.
`handler` : | A callback function.
`user_data` : | Arbitrary data that will be passed to `handler`.
`error` : | Location of a GError to store any possible errors.
Returns : | `TRUE` on success, `FALSE` otherwise, in which case `error` will be set.

### xfce_posix_signal_handler_shutdown ()

    void                xfce_posix_signal_handler_shutdown  ();

Frees all memory associated with the POSIX signal handling system and restores all default signal handlers.