## NAME

ACE_Sig_Handler - This is the main dispatcher of signals for ACE. It improves the existing UNIX signal handling mechanism by allowing C++ objects to handle signals in a way that avoids the use of global/static variables and functions.

## SYNOPSIS

    #include <ace/Signal.h>

    class ACE_Sig_Handler
    {
      public:
        ACE_Sig_Handler (void);
        virtual ~ACE_Sig_Handler (void);
        virtual int register_handler (
            int signum,
            ACE_Event_Handler *new_sh,
            ACE_Sig_Action *new_disp = 0,
            ACE_Event_Handler **old_sh = 0,
            ACE_Sig_Action *old_disp = 0
            );
        virtual int remove_handler (
            int signum,
            ACE_Sig_Action *new_disp = 0,
            ACE_Sig_Action *old_disp = 0,
            int sigkey = -1
            );
        static int sig_pending (void);
        static void sig_pending (int);
        virtual ACE_Event_Handler *handler (int signum);
        virtual ACE_Event_Handler *handler (
            int signum,
            ACE_Event_Handler *
            );
        static void dispatch (int, siginfo_t *, ucontext_t *);
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      protected:
        static int in_range (int signum);
        static sig_atomic_t sig_pending_;
      private:
        static ACE_Event_Handler *signal_handlers_[ACE_NSIG];
    };

## DESCRIPTION

Using this class a program can register an `ACE_Event_Handler` with the `ACE_Sig_Handler` in order to handle a designated `signum`. When a signal occurs that corresponds to this `signum`, the `handle_signal` method of the registered `ACE_Event_Handler` is invoked automatically.

## Registration and removal methods.

    virtual int register_handler (
        int signum,
        ACE_Event_Handler *new_sh,
        ACE_Sig_Action *new_disp = 0,
        ACE_Event_Handler **old_sh = 0,
        ACE_Sig_Action *old_disp = 0
        );

Add a new `ACE_Event_Handler` and a new sigaction associated with `signum`. Passes back the existing `ACE_Event_Handler` and its sigaction if pointers are non-zero. Returns -1 on failure and = 0 on success.

    virtual int remove_handler (
        int signum,
        ACE_Sig_Action *new_disp = 0,
        ACE_Sig_Action *old_disp = 0,
        int sigkey = -1
        );

Remove the `ACE_Event_Handler` currently associated with `signum`. `sigkey` is ignored in this implementation since there is only one instance of a signal handler. Install the new disposition (if given) and return the previous disposition (if desired by the caller). Returns 0 on success and -1 if `signum` is invalid.

Set/get signal status.

    static int sig_pending (void);

True if there is a pending signal.

    static void sig_pending (int);

Reset the value of `sig_pending_` so that no signal is pending.

## Set/get the handler associated with a particular signal.

    virtual ACE_Event_Handler *handler (int signum);

Return the list of `ACE_Sig_Handlers` associated with `signum`.

    virtual ACE_Event_Handler *handler (int signum, ACE_Event_Handler *);

Set a new `ACE_Event_Handler` that is associated with `signum`. Return the existing handler.

    static void dispatch (int, siginfo_t *, ucontext_t *);

Callback routine registered with sigaction(2) that dispatches the handle_signal() method of the appropriate pre-registered ACE_Event_Handler.

    void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## These methods and data members are shared by derived classes.

    static int in_range (int signum);

Check whether the SIGNUM is within the legal range of signals.

    static sig_atomic_t sig_pending_;

Keeps track of whether a signal is pending.

## AUTHOR

Doug Schmidt

## LIBRARY

ace