Fix typos in the documentation
[git/git.git] / Documentation / technical / api-sigchain.txt
CommitLineData
ed296fe8
JK
1sigchain API
2============
3
4Code often wants to set a signal handler to clean up temporary files or
5other work-in-progress when we die unexpectedly. For multiple pieces of
6code to do this without conflicting, each piece of code must remember
7the 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
16Sigchain is a tiny library for keeping a stack of handlers. Your handler
17and 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
469bfc96 35Handlers are given the typedef of sigchain_fun. This is the same type
ed296fe8
JK
36that is given to signal() or sigaction(). It is perfectly reasonable to
37push SIG_DFL or SIG_IGN onto the stack.
38
39You can sigchain_push and sigchain_pop individual signals. For
40convenience, sigchain_push_common will push the handler onto the stack
41for many common signals.