1 //! Unix-specific types for signal handling.
4 //! `Signal` type for receiving notifications of signals.
7 #![cfg_attr(docsrs, doc(cfg(all(unix, feature = "signal"))))]
10 use crate::runtime::signal::Handle;
11 use crate::signal::registry::{globals, EventId, EventInfo, Globals, Init, Storage};
12 use crate::signal::RxFuture;
64 /// Represents the specific kind of signal to listen for.
69     /// Allows for listening to any valid OS signal.
74     /// # use tokio::signal::unix::SignalKind;
89     /// Get the signal's numeric value.
92     /// # use tokio::signal::unix::SignalKind;
100     /// Represents the `SIGALRM` signal.
102     /// On Unix systems this signal is sent when a real-time timer has expired.
103     /// By default, the process is terminated by this signal.
108     /// Represents the `SIGCHLD` signal.
110     /// On Unix systems this signal is sent when the status of a child process
111     /// has changed. By default, this signal is ignored.
116     /// Represents the `SIGHUP` signal.
118     /// On Unix systems this signal is sent when the terminal is disconnected.
119     /// By default, the process is terminated by this signal.
124     /// Represents the `SIGINFO` signal.
126     /// On Unix systems this signal is sent to request a status update from the
127     /// process. By default, this signal is ignored.
139     /// Represents the `SIGINT` signal.
141     /// On Unix systems this signal is sent to interrupt a program.
142     /// By default, the process is terminated by this signal.
147     /// Represents the `SIGIO` signal.
149     /// On Unix systems this signal is sent when I/O operations are possible
150     /// on some file descriptor. By default, this signal is ignored.
155     /// Represents the `SIGPIPE` signal.
157     /// On Unix systems this signal is sent when the process attempts to write
159     /// this signal.
164     /// Represents the `SIGQUIT` signal.
166     /// On Unix systems this signal is sent to issue a shutdown of the
168     /// By default, the process is terminated by this signal.
173     /// Represents the `SIGTERM` signal.
175     /// On Unix systems this signal is sent to issue a shutdown of the
176     /// process. By default, the process is terminated by this signal.
181     /// Represents the `SIGUSR1` signal.
183     /// On Unix systems this is a user defined signal.
184     /// By default, the process is terminated by this signal.
189     /// Represents the `SIGUSR2` signal.
191     /// On Unix systems this is a user defined signal.
192     /// By default, the process is terminated by this signal.
197     /// Represents the `SIGWINCH` signal.
199     /// On Unix systems this signal is sent when the terminal window is resized.
200     /// By default, this signal is ignored.
234 /// Our global signal handler for all signals registered by this module.
236 /// The purpose of this signal handler is to primarily:
238 /// 1. Flag that our specific signal was received (e.g. store an atomic flag)
241 /// Those two operations should both be async-signal safe.
242 fn action(globals: &'static Globals, signal: libc::c_int) {  in action()
243     globals.record_event(signal as EventId);  in action()
251 /// Enables this module to receive signal notifications for the `signal`
254 /// This will register the signal handler if it hasn't already been registered,
256 fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> {  in signal_enable()
257     let signal = signal.0;  in signal_enable()  localVariable
258     if signal < 0 || signal_hook_registry::FORBIDDEN.contains(&signal) {  in signal_enable()
261             format!("Refusing to register signal {signal}"),  in signal_enable()
265     // Check that we have a signal driver running  in signal_enable()
269     let siginfo = match globals.storage().get(signal as EventId) {  in signal_enable()
271         None => return Err(io::Error::new(io::ErrorKind::Other, "signal too large")),  in signal_enable()
276             signal_hook_registry::register(signal, move || action(globals, signal)).map(|_| ())  in signal_enable()
283     // If the call_once failed, it won't be retried on the next attempt to register the signal. In  in signal_enable()
290             "Failed to register signal handler",  in signal_enable()
295 /// An listener for receiving a particular type of OS signal.
301 /// In general signal handling on Unix is a pretty tricky topic, and this
303 /// mind when using `Signal` streams:
306 ///   together sometimes. This `Signal` stream is also no exception here in
307 ///   that it will also coalesce signals. That is, even if the signal handler
308 ///   for this process runs multiple times, the `Signal` stream may only return
309 ///   one signal notification. Specifically, before `poll` is called, all
310 ///   signal notifications are coalesced into one item returned from `poll`.
311 ///   Once `poll` has been called, however, a further signal is guaranteed to
315 ///   *at least one* signal, but possibly more.
317 /// * Signal handling in general is relatively inefficient. Although some
319 ///   having millions of signal channels open.
327 /// The first time that a `Signal` instance is registered for a particular
328 /// signal kind, an OS signal-handler is installed which replaces the default
329 /// platform behavior when that signal is received, **for the duration of the
333 /// receives `SIGINT`. But, when a `Signal` instance is created to listen for
334 /// this signal, the next `SIGINT` that arrives will be translated to a stream
335 /// event, and the process will continue to execute. **Even if this `Signal`
339 /// Thus, applications should take care to ensure the expected signal behavior
347 /// use tokio::signal::unix::{signal, SignalKind};
352 ///     let mut sig = signal(SignalKind::hangup())?;
354 ///     // Print whenever a HUP signal is received
357 ///         println!("got signal HUP");
363 pub struct Signal {  struct
368 /// process receives the specified signal `kind`.
371 /// The `Signal` stream is an infinite stream which will receive  argument
372 /// notifications whenever a signal is received. More documentation can be
373 /// found on `Signal` itself, but to reiterate:
376 /// * Once a signal handler is registered with the process the underlying
377 ///   libc signal handler is never unregistered.
379 /// A `Signal` stream can be created for a particular signal number
380 /// multiple times. When a signal is received then all the associated
381 /// channels will receive the signal notification.
386 /// * If the previous initialization of this specific signal failed.
387 /// * If the signal is one of
395 pub fn signal(kind: SignalKind) -> io::Result<Signal> {  in signal()  argument
397     let rx = signal_with_handle(kind, handle.driver().signal())?;  in signal()
399     Ok(Signal {  in signal()
408     // Turn the signal delivery on once we are ready for it  in signal_with_handle()
414 impl Signal {  implementation
415     /// Receives the next signal notification event.
423     /// completes first, then it is guaranteed that no signal is lost.
430     /// use tokio::signal::unix::{signal, SignalKind};
435     ///     let mut stream = signal(SignalKind::hangup())?;
437     ///     // Print whenever a HUP signal is received
440     ///         println!("got signal HUP");
448     /// Polls to receive the next signal notification event, outside of an
455     ///  * `Poll::Ready(Some(()))` if a signal is available.
467     /// use tokio::signal::unix::Signal;
470     ///     signal: Signal,
478     ///         self.signal.poll_recv(cx)
494 impl InternalStream for Signal {  implementation
500 pub(crate) fn ctrl_c() -> io::Result<Signal> {  in ctrl_c()
501     signal(SignalKind::interrupt())  in ctrl_c()