README.md
1# Signal-hook
2
3[](https://github.com/vorner/signal-hook/actions)
4[](https://codecov.io/gh/vorner/signal-hook)
5[](https://docs.rs/signal-hook)
6
7Library for safe and correct Unix signal handling in Rust.
8
9Unix signals are inherently hard to handle correctly, for several reasons:
10
11* They are a global resource. If a library wants to set its own signal handlers,
12 it risks disturbing some other library. It is possible to chain the previous
13 signal handler, but then it is impossible to remove the old signal handlers
14 from the chains in any practical manner.
15* They can be called from whatever thread, requiring synchronization. Also, as
16 they can interrupt a thread at any time, making most handling race-prone.
17* According to the POSIX standard, the set of functions one may call inside a
18 signal handler is limited to very few of them. To highlight, mutexes (or other
19 locking mechanisms) and memory allocation and deallocation are *not* allowed.
20
21This library aims to solve some of the problems. It provides a global registry
22of actions performed on arrival of signals. It is possible to register multiple
23actions for the same signal and it is possible to remove the actions later on.
24If there was a previous signal handler when the first action for a signal is
25registered, it is chained (but the original one can't be removed).
26
27Besides the basic registration of an arbitrary action, several helper actions
28are provided to cover the needs of the most common use cases, available from
29safe Rust.
30
31For further details, see the [documentation](https://docs.rs/signal-hook).
32
33## Example
34
35(This likely does a lot more than you need in each individual application, it's
36more of a show-case of what everything is possible, not of what you need to do
37each time).
38
39```rust
40use std::io::Error;
41use std::sync::Arc;
42use std::sync::atomic::{AtomicBool, Ordering};
43
44fn main() -> Result<(), Error> {
45 let term = Arc::new(AtomicBool::new(false));
46 signal_hook::flag::register(signal_hook::consts::SIGTERM, Arc::clone(&term))?;
47 while !term.load(Ordering::Relaxed) {
48 // Do some time-limited stuff here
49 // (if this could block forever, then there's no guarantee the signal will have any
50 // effect).
51 }
52 Ok(())
53}
54```
55
56## License
57
58Licensed under either of
59
60 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
61 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
62
63at your option.
64
65### Contribution
66
67Unless you explicitly state otherwise, any contribution intentionally
68submitted for inclusion in the work by you, as defined in the Apache-2.0
69license, shall be dual licensed as above, without any additional terms
70or conditions.
71
){kind=link}
){kind=link}
){kind=link}