Struct HandlerOptions

pub struct HandlerOptions {
    pub handler: Option<SignalHandler>,
    pub ignore_child_stop_events: bool,
    pub recursive_handler: bool,
    pub system_call_restart: bool,
    pub auto_reset_handler: bool,
    /* private fields */
}

Available on Unix and crate feature signals only.

Options for installing a signal handler.

Example

use interprocess::os::unix::signal::{self, SignalType, SignalHandler};

let handler = unsafe {
    // Since signal handlers are restricted to a specific set of C functions, creating a
    // handler from an arbitrary function is unsafe because it might call a function
    // outside the list, and there's no real way to know that at compile time with the
    // current version of Rust. Since we're only using the write() system call here, this
    // is safe.
    SignalHandler::from_fn(|| {
        println!("You pressed Ctrl-C!");
    })
};

// Let's use the builder to customize the signal handler:
signal::HandlerOptions::for_signal(SignalType::KeyboardInterrupt)
    .set_new_handler(handler)
    .auto_reset_handler(true) // Let's remove the signal handler after it fires once.
    .system_call_restart(false) // Avoid restarting system calls and let them fail with the
                                // Interrupted error type. There normally isn't a reason to
                                // do this, but for the sake of the example, let's assume
                                // that there is.
    .set()?; // Finalize the builder by installing the handler.

Fields

handler: Option<SignalHandler>

The handler to be set up. If None, the handler is not changed by the call.

ignore_child_stop_events: bool

For the ChildProcessEvent signal, this option disables receiving the signal if it was generated because the child process was suspended (using any signal which suspends a process, such as Suspend or ForceSuspend) or resumed.

If enabled on a signal which is not ChildProcessEvent, a panic is produced in debug builds when set is called; in release builds, the flag is simply ignored.

recursive_handler: bool

Allow the signal handler to interrupt a previous invocation of itself. If disabled, the signal handler will disable its own signal when called and restore previous state when it finishes executing. If not, an infinite amount of signals can be received on top of each other, which is likely a stack overflow risk.

If enabled but the handler is set to use the default handling method from the OS, a panic is produced in debug builds when set is called; in release builds, the flag is simply ignored.

system_call_restart: bool

Automatically restart certain system calls instead of failing with the Interrupted error type. Some other system calls are not restarted with this function and may fail with Interrupted anyway. Consult your manual pages for more details.

auto_reset_handler: bool

Automatically reset the handler to the default handling method whenever it is executed.

If enabled but the handler is set to use the default handling method from the OS, a panic is produced in debug builds when set is called; in release builds, the flag is simply ignored.

Implementations

impl HandlerOptions

pub fn for_signal(signal: SignalType) -> Self

Creates a builder for a handler for the specified signal.

pub fn for_rtsignal(rtsignal: u32) -> Self

Creates a builder for a handler for the specified real-time signal.

Panics

Guaranteed to panic if the specified real-time signal is outside the range of real-time signals supported by the OS. See NUM_REALTIME_SIGNALS.

pub fn set_new_handler(self, handler: impl Into<Option<SignalHandler>>) -> Self

Sets the handler for the signal to the specified value. If None, the old value is used.

pub fn ignore_child_stop_events(self, ignore: impl Into<bool>) -> Self

Sets the ignore_child_stop_events flag to the specified value.

pub fn recursive_handler(self, recursive: impl Into<bool>) -> Self

Sets the recursive_handler flag to the specified value.

pub fn system_call_restart(self, restart: impl Into<bool>) -> Self

Sets the system_call_restart flag to the specified value.

pub fn auto_reset_handler(self, reset: impl Into<bool>) -> Self

Sets the auto_reset_handler flag to the specified value.

pub fn set(self) -> Result<(), SetHandlerError>

Installs the signal handler.

pub unsafe fn set_unsafe(self) -> Result<(), SetHandlerError>

Installs the signal handler, even if the signal being handled is unsafe.

Safety

The handler and all code that may or may not execute afterwards must be prepared for the aftermath of what might’ve caused the signal.

SegmentationFault or BusError are most likely caused by undefined behavior invoked from Rust (the former is caused by dereferencing invalid memory, the latter is caused by dereferencing an incorrectly aligned pointer on ISAs like ARM which do not tolerate misaligned pointers), which means that the program is unsound and the only meaningful thing to do is to capture as much information as possible in a safe way – preferably using OS services to create a dump, rather than trying to read the program’s global state, which might be irreversibly corrupted – and write the crash dump to some on-disk location.

Trait Implementations

impl Clone for HandlerOptions

fn clone(&self) -> HandlerOptions

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HandlerOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for HandlerOptions

fn eq(&self, other: &HandlerOptions) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for HandlerOptions

impl Eq for HandlerOptions

impl StructuralPartialEq for HandlerOptions