Struct interprocess::os::unix::signal::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,
    // some fields omitted
}

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 system calls, creating a
    // handler from an arbitrary function is unsafe because it might perform a system call
    // 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, for example, might be caused by hitting a stack protector as a response to a thread's stack overflow — in such a case, continuing the program might result in undefined behavior. The Rust runtime actually sets its own handler for SegmentationFault signals which converts those signals to proper shutdowns, i.e. ignoring it essentially disables stack protectors, which is unsound.

Trait Implementations

impl Clone for HandlerOptions

fn clone(&self) -> HandlerOptions

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for HandlerOptions

impl Debug for HandlerOptions

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

Formats the value using the given formatter.

impl Eq for HandlerOptions

impl PartialEq<HandlerOptions> for HandlerOptions

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralEq for HandlerOptions

impl StructuralPartialEq for HandlerOptions