POSIX Signal Handling
3
LIBXFCE4UTIL Library

# 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.