Enum interprocess::os::unix::signal::SignalType

#[repr(i32)]
#[non_exhaustive]pub enum SignalType {
    Hangup,
    KeyboardInterrupt,
    QuitAndDump,
    IllegalInstruction,
    Abort,
    MathException,
    Kill,
    SegmentationFault,
    BrokenPipe,
    AlarmClock,
    Termination,
    UserSignal1,
    UserSignal2,
    ChildProcessEvent,
    Continue,
    ForceSuspend,
    Suspend,
    TerminalInputWhileInBackground,
    TerminalOutputWhileInBackground,
    PollNotification,
    MemoryBusError,
    ProfilerClock,
    UserModeProfilerClock,
    InvalidSystemCall,
    Breakpoint,
    OutOfBandDataAvailable,
    CpuTimeLimitExceeded,
    FileSizeLimitExceeded,
}

All standard signal types as defined in POSIX.1-2001.

The values can be safely and quickly converted to i32/u32. The reverse process involves safety checks, making sure that unknown signal values are never stored.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Hangup

SIGHUP — lost connection to controlling terminal. Opting out of this signal is recommended if the process does not need to stop after the user who started it logs out.

Default handler: process termination.

KeyboardInterrupt

SIGINT — keyboard interrupt, usually sent by pressing Ctrl+C by the terminal. This signal is typically set to be ignored if the program runs an interactive interface: GUI/TUI, interactive shell (the Python shell, for example) or any other kind of interface which runs in a loop, as opposed to a command-line invocation of the program which reads its standard input or command-line arguments, performs a task and exits. If the interactive interface is running a lengthy operation, a good idea is to temporarily re-enable the signal and abort the lengthy operation if the signal is received, then disable it again.

Default handler: process termination.

QuitAndDump

SIGQUIT — request to perform a core dump and quit, usually sent by pressing Ctrl+\. This signal normally should not be overriden or masked out — the core dump is performed automatically by the OS.

Default handler: process termination with a core dump.

IllegalInstruction

SIGILL — illegal or malformed instruction exception, generated by the CPU whenever such an instruction is executed. This signal normally should not be overriden or masked out, since it likely means that the executable file or the memory of the process has been corrupted and further execution is a risk of invoking negative consequences.

For reasons described above, this signal is considered unsafe — handling it requires using set_unsafe_handler.

Default handler: process termination with a core dump.

Abort

SIGABRT — abnormal termination requested. This signal is typically invoked by the program itself, using std::process::abort or the equivalent C function; still, like any other signal, it can be sent from outside the process.

Default handler: process termination with a core dump.

MathException

SIGFPE — mathematical exception. This signal is generated whenever an undefined mathematical operation is performed — mainly integer division by zero.

Default handler: process termination with a core dump.

Kill

SIGKILL — forced termination. This signal can only be sent using the usual signal sending procedures and, unlike most other signals, cannot be masked out or handled at all. The main purpose for this signal is to stop a program which has masked out all other signals for malicious purposes or has stuck in such a state because of a bug.

Default handler: process termination, cannot be overriden or disabled.

SegmentationFault

SIGSEGV — invaid memory access. This signal is issued by the OS whenever the program tries to access an invalid memory location, such as the NULL pointer or simply an address outside the user-mode address space as established by the OS. The only case when this signal can be received by a Rust program is if memory unsafety occurs due to misuse of unsafe code. As such, it should normally not be masked out or handled, as it likely indicates a critical bug (soundness hole), executable file corruption or process memory corruption.

For reasons described above, this signal is considered unsafe — handling it requires using set_unsafe_handler.

Default handler: process termination with a core dump.

BrokenPipe

SIGPIPE — invalid access to an unnamed pipe. This signal is issued by the OS whenever a program attempts to write to an unnamed pipe which has no readers connected to it. If unexpected, this might mean abnormal termination of the process which the pipe was used to communicate with.

Default handler: process termination.

AlarmClock

SIGALRM — "alarm clock" signal. This signal is issued by the OS when the arranged amount of real (wall clock) time expires. This clock can be set using the alarm and setitimer system calls.

Default handler: process termination.

Termination

SIGTERM — request for termination. This signal can only be sent using the usual signal sending procedures. Unlike KeyboardInterrupt, this signal is not a request to break out of a lengthy operation, but rather to close the program as a whole. Signal handlers for this signal are expected to perform minimal cleanup and quick state save procedures and then exit.

Default handler: process termination.

UserSignal1

SIGUSR1 — user-defined signal 1. This signal, like UserSignal2, does not have a predefined meaning and is not produced by the OS. For this reason, it is typically used for interprocess communication between two programs familiar with each other, or in language runtimes to signal certain events, such as externally activated immediate garbage collection.

Default handler: process termination.

UserSignal2

SIGUSR2 — user-defined signal 2. This signal is similar to UserSignal1 and has the same properties, but is a distinct signal nonetheless.

Default handler: process termination.

ChildProcessEvent

SIGCHLD — child process suspended, resumed or terminated. This signal is issued by the OS whenever a child process is suspended/resumed or terminated by a signal or otherwise.

Default handler: ignore.

Continue

SIGCONT — resume the process after being suspended. This signal can be sent to a process by an external program when it wishes to resume that process after it being suspended in a stopped state.

Default handler: continue execution.

ForceSuspend

SIGSTOP — forcefully stop a process temporarily. This signal can only be sent to a process by an external program. Unlike Suspend, this signal cannot be masked out or handled, i.e. it is guaranteed to be able to temporarily stop a process from executing without forcefully terminating it. The process can then be restarted using Continue.

Default handler: temporarily stop process, cannot be overriden or disabled.

Suspend

SIGTSTP — temporarily stop a process. This signal can only be sent to a process by an external program. Unlike ForceSuspend, this signal can be masked out or handled by the process which is requested to stop. The process can then be restarted using Continue.

Default handler: temporarily stop process.

TerminalInputWhileInBackground

SIGTTIN — attempt to read from standard input while in the background. This signal is issued by the OS whenever a process which is under job control tries to read from standard input but is in the background, i.e. temporarily detached from the terminal.

Default handler: temporarily stop process.

TerminalOutputWhileInBackground

SIGTTOU — attempt to write to standard output while in the background. This signal is issued by the OS whenever a process which is under job control tries to write to standard input but is in the background, i.e. temporarily detached from the terminal.

Default handler: temporarily stop process.

PollNotification

SIGPOLL — watched file descriptor event. This signal is issued by the OS when a file descriptor which has been enabled to interact with this signal has a state update.

Default handler: process termination.

MemoryBusError

SIGBUS — bus error. This signal is issued by the OS when a process does one of the following:

• Tries to access an invalid physical address. Normally, this should never happen — attempts to access invalid virtual memory are handled as segmentation faults, and invalid phyiscal addresses are typically not present in the address space of a program in user-mode.
• Performs an incorrectly aligned memory access. In Rust, this can only happen if unsafe code is misused to construct an incorrectly aligned pointer to a type which requires alignment which is more strict than simple one byte alignment. This is a direct sign of memory unsafety being invoked.
• Incorrect x86 segment register. This can only be acheieved using inline assembly or FFI (calling an external function written in assembly language or with usage of C/C++ inline assembly), and only on the x86 architecture. If an invalid value is loaded into the segment registers, the CPU generates this exception. This is either a sign of a failed advanced unsafe operation or a deliberate attempt to cryptically crash the program.

For reasons described above, this signal is considered unsafe — handling it requires using set_unsafe_handler.

Default handler: process termination with a core dump.

ProfilerClock

SIGPROF — profiler clock signal. This signal is issued by the OS when the arranged amount of CPU time expires. The time includes not only user-mode CPU time spent in the process, but also kernel-mode CPU time which the OS associates with the process. This is different from UserModeProfilerClock's behavior, which counts only user-mode CPU time. This clock can be set using the setitimer system call.

Default handler: process termination.

UserModeProfilerClock

SIGVTALRM — user-mode profiler clock signal. This signal is issued by the OS when the arranged amount of CPU time expires. Only user-mode CPU time is counted, in contrast to ProfilerClock, which counts kernel-mode time associated by the system with the process as well. This clock can be set using the setitimer system call.

Default handler: process termination.

InvalidSystemCall

SIGSYS — attempt to perform an invalid system call. This signal is issued by the OS when a system call receives invalid arguments. Normally, the C library functions used to perform system calls in Rust programs do not generate this signal — the only way to generate it is to send it to a process explicitly, use raw system call instructions or violate seccomp rules if it is enabled.

Default handler: process termination with a core dump.

Breakpoint

SIGTRAP — software breakpoint. This signal is issued by the OS when a breakpoint instruction is executed. On x86, the instruction to do so is int 3. This instruction is typically inserted by debuggers and code injection utilities.

Default handler: process termination with a core dump.

OutOfBandDataAvailable

SIGURG — out-of-band data received on a socket. This signal is issued by the OS when a socket owned by the process receives urgent out-of-band data.

Default handler: ignore.

CpuTimeLimitExceeded

SIGXCPU — assigned CPU time limit for the process was exceeded. This signal is issued by the OS if a CPU time limit for the process was set, when that limit expires. If not handled quickly, the system will issue a Kill signal to shut down the process forcefully, i.e. ignoring this signal won't lead to bypassing the limit. The setrlimit system call is used to set the soft limit for this signal and the hard limit, which invokes Kill.

Default handler: process termination with a core dump.

FileSizeLimitExceeded

SIGXFSZ — assigned file size limit for the process was exceeded. This signal is issued by the OS if a limit on the size of files which are written to by the process was set, when that limit is exceeded by the process. If ignored/handled, the offending system call fails with an error regardless of the handling method. The setrlimit system call is used to set the limit.

Default handler: process termination with a core dump.

Implementations

impl SignalType

pub fn is_unblockable(self) -> bool

Returns true if the value is a special signal which cannot be blocked or handled (Kill or ForceSuspend), false otherwise.

pub fn is_unsafe(self) -> bool

Returns true if the value is an unsafe signal which requires unsafe code when setting a handling method, false otherwise.

Trait Implementations

impl Clone for SignalType

fn clone(&self) -> SignalType

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for SignalType

impl Debug for SignalType

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

Formats the value using the given formatter.

impl Eq for SignalType

impl From<SignalType> for i32

fn from(op: SignalType) -> Self

Performs the conversion.

impl From<SignalType> for u32

fn from(op: SignalType) -> Self

Performs the conversion.

impl Hash for SignalType

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl PartialEq<SignalType> for SignalType

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

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl StructuralEq for SignalType

impl StructuralPartialEq for SignalType

impl TryFrom<i32> for SignalType

type Error = UnknownSignalError

The type returned in the event of a conversion error.

fn try_from(value: i32) -> Result<Self, Self::Error>

Performs the conversion.