Documentation/technical/api-sigchain.txt

   1 sigchain API
   2 ============
   3
   4 Code often wants to set a signal handler to clean up temporary files or
   5 other work-in-progress when we die unexpectedly. For multiple pieces of
   6 code to do this without conflicting, each piece of code must remember
   7 the old value of the handler and restore it either when:
   8
   9   1. The work-in-progress is finished, and the handler is no longer
  10      necessary. The handler should revert to the original behavior
  11      (either another handler, SIG_DFL, or SIG_IGN).
  12
  13   2. The signal is received. We should then do our cleanup, then chain
  14      to the next handler (or die if it is SIG_DFL).
  15
  16 Sigchain is a tiny library for keeping a stack of handlers. Your handler
  17 and installation code should look something like:
  18
  19 ------------------------------------------
  20   void clean_foo_on_signal(int sig)
  21   {
  22           clean_foo();
  23           sigchain_pop(sig);
  24           raise(sig);
  25   }
  26
  27   void other_func()
  28   {
  29           sigchain_push_common(clean_foo_on_signal);
  30           mess_up_foo();
  31           clean_foo();
  32   }
  33 ------------------------------------------
  34
  35 Handlers are given the typedef of sigchain_fun. This is the same type
  36 that is given to signal() or sigaction(). It is perfectly reasonable to
  37 push SIG_DFL or SIG_IGN onto the stack.
  38
  39 You can sigchain_push and sigchain_pop individual signals. For
  40 convenience, sigchain_push_common will push the handler onto the stack
  41 for many common signals.