535cdff164f1f1cdf829f18fa192783efb9f0086
[git/git.git] / 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 typdef 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.