Module signal

Available on Unix and crate feature signals only.

Signal support for Unix-like systems.

Signals in Unix are much more functional and versatile than ANSI C signals – there is simply much, much more of them. In addition to that, there is a special group of signals called “real-time signals” (more on those below).

Main signals

The SignalType enumeration provides all standard signals as defined in POSIX.1-2001. More signal types may be added later, which is why exhaustively matching on it is not possible. It can be cheaply converted to a 32-bit integer, though. See its documentation for more on conversions.

The set_handler function is used to create an association between a SignalType and a signal handling strategy.

Real-time signals

In addition to usual signals, there’s a special group of signals called “real-time signals”. Those signals do not have fixed identifiers and are not generated by the system or kernel. Instead, they can only be sent between processes.

Signal-safe C functions

Very few C functions can be called from a signal handler. Allocating memory, using the thread API and manipulating interval timers, for example, is prohibited in a signal handler. Calling a function which is not signal safe results in undefined behavior, i.e. memory unsafety. Rather than excluding certain specific functions, the POSIX specification only speicifies functions which are signal-safe. The following C functions are guaranteed to be safe to call from a signal handler:

• _Exit
• _exit
• abort
• accept
• access
• aio_error
• aio_return
• aio_suspend
• alarm
• bind
• cfgetispeed
• cfgetospeed
• cfsetispeed
• cfsetospeed
• chdir
• chmod
• chown
• clock_gettime
• close
• connect
• creat
• dup
• dup2
• execle
• execve
• fchmod
• fchown
• fcntl
• fdatasync
• fork
• fpathconf
• fstat
• fsync
• ftruncate
• getegid
• geteuid
• getgid
• getgroups
• getpeername
• getpgrp
• getpid
• getppid
• getsockname
• getsockopt
• getuid
• kill
• link
• listen
• lseek
• lstat
• mkdir
• mkfifo
• open
• pathconf
• pause
• pipe
• poll
• posix_trace_event
• pselect
• raise
• read
• readlink
• recv
• recvfrom
• recvmsg
• rename
• rmdir
• select
• sem_post
• send
• sendmsg
• sendto
• setgid
• setpgid
• setsid
• setsockopt
• setuid
• shutdown
• sigaction
• sigaddset
• sigdelset
• sigemptyset
• sigfillset
• sigismember
• signal
• sigpause
• sigpending
• sigprocmask
• sigqueue
• sigset
• sigsuspend
• sleep
• sockatmark
• socket
• socketpair
• stat
• symlink
• sysconf
• tcdrain
• tcflow
• tcflush
• tcgetattr
• tcgetpgrp
• tcsendbreak
• tcsetattr
• tcsetpgrp
• time
• timer_getoverrun
• timer_gettime
• timer_settime
• times
• umask
• uname
• unlink
• utime
• wait
• waitpid
• write

Many Rust crates, including the standard library, use signal-unsafe functions not on this list in safe code. For example, Vec, Box and Rc/Arc perform memory allocations, and Mutex/RwLock perform pthread calls. For this reason, creating a signal hook is an unsafe operation.

Structs

HandlerOptions

Options for installing a signal handler.

SignalHook

A function which can be used as a signal handler.

UnknownSignalError

Error type returned when a conversion from i32/u32 to SignalType fails.

Enums

SetHandlerError

The error produced when setting a signal handler fails.

SignalHandler

A signal handling method.

SignalType

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

Constants

NUM_REALTIME_SIGNALS

How many real-time signals are supported. Remember that real-time signals start from 0, so this number is higher than the highest possible real-time signal by 1.

REALTIME_SIGNALS_SUPPORTED

Whether real-time signals are supported at all.

Functions

is_valid_rtsignal

Returns true if the specified signal is a valid real-time signal value, false otherwise.

send

Sends the specified signal to the specified process. If the specified signal is None, no signal is sent and only a privilege check is performed instead.

send_rt

Sends the specified real-time signal to the specified process. If the specified signal is None, no signal is sent and only a privilege check is performed instead.

send_rt_to_group

Sends the specified real-time signal to the specified process. If the specified signal is None, no signal is sent and only a privilege check is performed instead.

send_to_group

Sends the specified signal to the specified process group. If the specified signal is None, no signal is sent and only a privilege check is performed instead.

set_handler

Installs the specified handler for the specified standard signal, using the default values for the flags.

set_rthandler

Installs the specified handler for the specified real-time signal, using the default values for the flags.

set_unsafe_handler^⚠

Installs the specified handler for the specified unsafe signal, using the default values for the flags.