Emulating default actions

Author: vorner

CHANGELOG.md

@@ -1,3 +1,5 @@
+* `low_level::emulate_default_handler` to emulate whatever default handler would
+  do.
 * `low_level::signal_name` to look up human readable name.
 * The `Origin`'s debug output now contains the human readable name of the
   signal.

examples/print.rs

@@ -0,0 +1,27 @@
+use libc::c_int;
+use signal_hook::consts::signal::*;
+use signal_hook::low_level;
+
+use std::io::Error;
+
+#[cfg(feature = "extended-siginfo")]
+type Signals =
+    signal_hook::iterator::SignalsInfo<signal_hook::iterator::exfiltrator::origin::WithOrigin>;
+
+#[cfg(not(feature = "extended-siginfo"))]
+use signal_hook::iterator::Signals;
+
+fn main() -> Result<(), Error> {
+    const SIGNALS: &[c_int] = &[
+        SIGTERM, SIGQUIT, SIGINT, SIGTSTP, SIGWINCH, SIGHUP, SIGCHLD, SIGCONT,
+    ];
+    let mut sigs = Signals::new(SIGNALS)?;
+    for signal in &mut sigs {
+        eprintln!("Received signal {:?}", signal);
+        #[cfg(feature = "extended-siginfo")]
+        let signal = signal.signal;
+        // After printing it, do whatever the signal was supposed to do in the first place
+        low_level::emulate_default_handler(signal)?;
+    }
+    Ok(())
+}

src/flag.rs

@@ -141,22 +141,26 @@ use std::io::Error;
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::Arc;
 
-use libc::c_int;
+use libc::{c_int, EINVAL};
 
-use crate::SigId;
+use crate::{low_level, SigId};
 
 /// Registers an action to set the flag to `true` whenever the given signal arrives.
+///
+/// # Panics
+///
+/// If the signal is one of the forbidden.
 pub fn register(signal: c_int, flag: Arc<AtomicBool>) -> Result<SigId, Error> {
     // We use SeqCst for two reasons:
     // * Signals should not come very often, so the performance does not really matter.
     // * We promise the order of actions, but setting different atomics with Relaxed or similar
     //   would not guarantee the effective order.
-    unsafe { crate::low_level::register(signal, move || flag.store(true, Ordering::SeqCst)) }
+    unsafe { low_level::register(signal, move || flag.store(true, Ordering::SeqCst)) }
 }
 
 /// Registers an action to set the flag to the given value whenever the signal arrives.
 pub fn register_usize(signal: c_int, flag: Arc<AtomicUsize>, value: usize) -> Result<SigId, Error> {
-    unsafe { crate::low_level::register(signal, move || flag.store(value, Ordering::SeqCst)) }
+    unsafe { low_level::register(signal, move || flag.store(value, Ordering::SeqCst)) }
 }
 
 /// Terminate the application on a signal if the given condition is true.
@@ -175,17 +179,53 @@ pub fn register_usize(signal: c_int, flag: Arc<AtomicUsize>, value: usize) -> Re
 /// shutdown on the second run. Note that it matters in which order the actions are registered (the
 /// shutdown must go first). And yes, this also allows asking the user „Do you want to terminate“
 /// and disarming the abrupt shutdown if the user answers „No“.
+///
+/// # Panics
+///
+/// If the signal is one of the forbidden.
 pub fn register_conditional_shutdown(
     signal: c_int,
     status: c_int,
     condition: Arc<AtomicBool>,
 ) -> Result<SigId, Error> {
     let action = move || {
         if condition.load(Ordering::SeqCst) {
-            crate::low_level::exit(status);
+            low_level::exit(status);
+        }
+    };
+    unsafe { low_level::register(signal, action) }
+}
+
+/// Conditionally runs an emulation of the default action on the given signal.
+///
+/// If the provided condition is true at the time of invoking the signal handler, the equivalent of
+/// the default action of the given signal is run. It is a bit similar to
+/// [`register_conditional_shutdown`], except that it doesn't terminate for non-termination
+/// signals, it runs their default handler.
+///
+/// # Panics
+///
+/// If the signal is one of the forbidden
+///
+/// # Errors
+///
+/// Similarly to the [`emulate_default_handler`][low_level::emulate_default_handler] function, this
+/// one looks the signal up in a table. If it is unknown, an error is returned.
+///
+/// Additionally to that, any errors that can be caused by a registration of a handler can happen
+/// too.
+pub fn register_conditional_default(
+    signal: c_int,
+    condition: Arc<AtomicBool>,
+) -> Result<SigId, Error> {
+    // Verify we know about this particular signal.
+    low_level::signal_name(signal).ok_or_else(|| Error::from_raw_os_error(EINVAL))?;
+    let action = move || {
+        if condition.load(Ordering::SeqCst) {
+            let _ = low_level::emulate_default_handler(signal);
         }
     };
-    unsafe { crate::low_level::register(signal, action) }
+    unsafe { low_level::register(signal, action) }
 }
 
 #[cfg(test)]

src/lib.rs

@@ -103,7 +103,8 @@
 //!   does not restore the default handler (such behaviour would be at times inconsistent with
 //!   making the actions independent and there's no reasonable way to do so in a race-free way in a
 //!   multi-threaded program while also dealing with signal handlers registered with other
-//!   libraries). It is, however, possible to *emulate* the default handler ‒ there are only 4
+//!   libraries). It is, however, possible to *emulate* the default handler (see the
+//!   [`emulate_default_handler`][low_level::emulate_default_handler]) ‒ there are only 4
 //!   default handlers:
 //!   - Ignore. This is easy to emulate.
 //!   - Abort. Depending on if you call it from within a signal handler of from outside, the
@@ -269,8 +270,8 @@
 //!                 if has_terminal {
 //!                     app.restore_term();
 //!                     has_terminal = false;
-//!                     // And actually stop ourselves, by a little trick.
-//!                     low_level::raise(SIGSTOP)?;
+//!                     // And actually stop ourselves.
+//!                     low_level::emulate_default_handler(SIGTSTP)?;
 //!                 }
 //!             }
 //!             SIGCONT => {

src/low_level/mod.rs

@@ -16,7 +16,7 @@ mod signal_details;
 
 pub use signal_hook_registry::{register, unregister};
 
-pub use self::signal_details::signal_name;
+pub use self::signal_details::{emulate_default_handler, signal_name};
 
 /// The usual raise, just the safe wrapper around it.
 ///

src/low_level/signal_details.rs

@@ -1,64 +1,82 @@
 //! Providing auxiliary information for signals.
 
-use libc::c_int;
+use std::io::Error;
+use std::mem;
+use std::ptr;
+
+use libc::{c_int, EINVAL};
 
 use crate::consts::signal::*;
+use crate::low_level;
+
+#[derive(Clone, Copy, Debug)]
+enum DefaultKind {
+    Ignore,
+    #[cfg(not(windows))]
+    Stop,
+    Term,
+}
 
 struct Details {
     signal: c_int,
     name: &'static str,
+    default_kind: DefaultKind,
 }
 
 macro_rules! s {
-    ($name: expr) => {
+    ($name: expr, $kind: ident) => {
         Details {
             signal: $name,
             name: stringify!($name),
+            default_kind: DefaultKind::$kind,
         }
     };
 }
 
 #[cfg(not(windows))]
 const DETAILS: &[Details] = &[
-    s!(SIGABRT),
-    s!(SIGALRM),
-    s!(SIGBUS),
-    s!(SIGCHLD),
-    s!(SIGCONT),
-    s!(SIGFPE),
-    s!(SIGHUP),
-    s!(SIGILL),
-    s!(SIGINT),
-    s!(SIGIO),
-    s!(SIGKILL),
-    s!(SIGPIPE),
-    s!(SIGPROF),
-    s!(SIGQUIT),
-    s!(SIGSEGV),
-    s!(SIGSTOP),
-    s!(SIGSYS),
-    s!(SIGTERM),
-    s!(SIGTRAP),
-    s!(SIGTSTP),
-    s!(SIGTTIN),
-    s!(SIGTTOU),
-    s!(SIGURG),
-    s!(SIGUSR1),
-    s!(SIGUSR2),
-    s!(SIGVTALRM),
-    s!(SIGWINCH),
-    s!(SIGXCPU),
-    s!(SIGXFSZ),
+    s!(SIGABRT, Term),
+    s!(SIGALRM, Term),
+    s!(SIGBUS, Term),
+    s!(SIGCHLD, Ignore),
+    // Technically, continue the process... but this is not done *by* the process.
+    s!(SIGCONT, Ignore),
+    s!(SIGFPE, Term),
+    s!(SIGHUP, Term),
+    s!(SIGILL, Term),
+    s!(SIGINT, Term),
+    s!(SIGIO, Ignore),
+    // Can't override anyway, but...
+    s!(SIGKILL, Term),
+    s!(SIGPIPE, Term),
+    s!(SIGPROF, Term),
+    s!(SIGQUIT, Term),
+    s!(SIGSEGV, Term),
+    // Can't override anyway, but...
+    s!(SIGSTOP, Stop),
+    s!(SIGSYS, Term),
+    s!(SIGTERM, Term),
+    s!(SIGTRAP, Term),
+    s!(SIGTSTP, Stop),
+    s!(SIGTTIN, Stop),
+    s!(SIGTTOU, Stop),
+    s!(SIGURG, Ignore),
+    s!(SIGUSR1, Term),
+    s!(SIGUSR2, Term),
+    s!(SIGVTALRM, Term),
+    s!(SIGWINCH, Ignore),
+    s!(SIGXCPU, Term),
+    s!(SIGXFSZ, Term),
 ];
 
 #[cfg(windows)]
 const DETAILS: &[Details] = &[
-    s!(SIGABRT),
-    s!(SIGFPE),
-    s!(SIGILL),
-    s!(SIGINT),
-    s!(SIGSEGV),
-    s!(SIGTERM),
+    s!(SIGABRT, Term),
+    s!(SIGFPE, Term),
+    s!(SIGILL, Term),
+    s!(SIGINT, Term),
+    s!(SIGSEGV, Term),
+    s!(SIGTERM, Term),
 ];
 
 /// Provides a human-readable name of a signal.
@@ -77,6 +95,90 @@ pub fn signal_name(signal: c_int) -> Option<&'static str> {
     DETAILS.iter().find(|d| d.signal == signal).map(|d| d.name)
 }
 
+#[cfg(not(windows))]
+fn restore_default(signal: c_int) -> Result<(), Error> {
+    unsafe {
+        // A C structure, supposed to be memset to 0 before use.
+        let mut action: libc::sigaction = mem::zeroed();
+        action.sa_sigaction = libc::SIG_DFL as _;
+        if libc::sigaction(signal, &action, ptr::null_mut()) == 0 {
+            Ok(())
+        } else {
+            Err(Error::last_os_error())
+        }
+    }
+}
+
+#[cfg(windows)]
+fn restore_default(signal: c_int) -> Result<(), Error> {
+    unsafe {
+        // SIG_DFL = 0, but not in libc :-(
+        if libc::signal(signal, 0) == 0 {
+            Ok(())
+        } else {
+            Err(Error::last_os_error())
+        }
+    }
+}
+
+/// Emulates the behaviour of a default handler for the provided signal.
+///
+/// This function does its best to provide the same action as the default handler would do, without
+/// disrupting the rest of the handling of such signal in the application. It is also
+/// async-signal-safe.
+///
+/// This function necessarily looks up the appropriate action in a table. That means it is possible
+/// your system has a signal that is not known to this function. In such case an error is returned
+/// (equivalent of `EINVAL`).
+///
+/// See also the [`register_conditional_default`][crate::flag::register_conditional_default].
+///
+/// # Warning
+///
+/// There's a short race condition in case of signals that terminate (either with or without a core
+/// dump). The emulation first resets the signal handler back to default (as the application is
+/// going to end, it's not a problem) and invokes it. But if some other thread installs a signal
+/// handler in the meantime (without assistance from `signal-hook`), it can happen this will be
+/// invoked by the re-raised signal.
+///
+/// This function will still terminate the application (there's a fallback on `abort`), the risk is
+/// invoking the newly installed signal handler. Note that manipulating the low-level signals is
+/// always racy in a multi-threaded program, therefore the described situation is already
+/// discouraged.
+///
+/// If you are uneasy about such race condition, the recommendation is to run relevant termination
+/// routine manually ([`exit`][super::exit] or [`abort`][super::abort]); they always do what they
+/// say, but slightly differ in externally observable behaviour from termination by a signal (the
+/// exit code will specify that the application exited, not that it terminated with a signal in the
+/// first case, and `abort` terminates on `SIGABRT`, so the detected termination signal may be
+/// different).
+pub fn emulate_default_handler(signal: c_int) -> Result<(), Error> {
+    #[cfg(not(windows))]
+    {
+        if signal == SIGSTOP || signal == SIGKILL {
+            return low_level::raise(signal);
+        }
+    }
+    let kind = DETAILS
+        .iter()
+        .find(|d| d.signal == signal)
+        .map(|d| d.default_kind)
+        .ok_or_else(|| Error::from_raw_os_error(EINVAL))?;
+    match kind {
+        DefaultKind::Ignore => Ok(()),
+        #[cfg(not(windows))]
+        DefaultKind::Stop => low_level::raise(SIGSTOP),
+        DefaultKind::Term => {
+            if let Ok(()) = restore_default(signal) {
+                let _ = low_level::raise(signal);
+            }
+            // Fallback if anything failed or someone managed to put some other action in in
+            // between.
+            unsafe { libc::abort() }
+        }
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;