unix::signal
The signal module provides support for Unix signal handlers. Typical
applications will provide a signal handler to handle to configure it for the
desired signal, possibly along with flags and a signal mask. This function
returns the previous signal handler, which can be passed to restore to
restore the previous behavior.
Signal handling is stupidly complicated and easy to get wrong. The standard
library makes little effort to help you deal with this. Consult your local man
pages, particularly signal-safety(7) on Linux, and perhaps a local priest as
well. We advise you to get out of the signal handler as soon as possible, for
example via the "self-pipe trick".
Note that the necessary sa_restorer functionality is implemented (and imposed)
by the standard library.
Index
Types
type flag;
type handler;
type how;
type siginfo;
type sigaction;
type signal;
type sigset;
Constants
const SIGABRT: signal;
const SIGALRM: signal;
const SIGBUS: signal;
const SIGCHLD: signal;
const SIGCONT: signal;
const SIGFPE: signal;
const SIGHUP: signal;
const SIGILL: signal;
const SIGINT: signal;
const SIGIO: signal;
const SIGKILL: signal;
const SIGPIPE: signal;
const SIGPOLL: signal;
const SIGPROF: signal;
const SIGPWR: signal;
const SIGQUIT: signal;
const SIGSEGV: signal;
const SIGSTOP: signal;
const SIGSYS: signal;
const SIGTERM: signal;
const SIGTRAP: signal;
const SIGTSTP: signal;
const SIGTTIN: signal;
const SIGTTOU: signal;
const SIGURG: signal;
const SIGUSR1: signal;
const SIGUSR2: signal;
const SIGVTALRM: signal;
const SIGWINCH: signal;
const SIGXCPU: signal;
const SIGXFSZ: signal;
Functions
fn block(signal...) sigset;
fn getprocmask() sigset;
fn handle(signal, *handler, (flag | sigset)...) sigaction;
fn newsigset(signal...) sigset;
fn read(io::file) (siginfo | errors::error);
fn restore(signal, *sigaction) void;
fn setprocmask(how, *sigset) sigset;
fn signalfd(signal...) (io::file | errors::error);
fn signame(signal) const str;
fn sigset_add(*sigset, signal...) void;
fn sigset_del(*sigset, signal...) void;
fn sigset_empty(*sigset) void;
fn sigset_member(*sigset, signal) bool;
fn unblock(signal...) sigset;
fn update(io::file, signal...) (void | errors::error);
Types
type flag
type flag = enum {
NOCLDSTOP = rt::SA_NOCLDSTOP: int,
NOCLDWAIT = rt::SA_NOCLDWAIT: int,
ONSTACK = rt::SA_ONSTACK: int,
RESTART = rt::SA_RESTART: int,
NODEFER = rt::SA_NODEFER: int,
RESETHAND = rt::SA_RESETHAND: int,
};
Flags used to configure the behavior of a signal handler.
type handler
type handler = fn(sig: int, info: *siginfo, ucontext: *void) void;
A function which handles a signal. The first argument is the signal number
which was caught, the second provides information about the signal, and the
third argument is the ucontext, which is usually ignored by most signal
handlers.
type how
type how = enum {
BLOCK = rt::SIG_BLOCK,
UNBLOCK = rt::SIG_UNBLOCK,
SETMASK = rt::SIG_SETMASK,
};
Defines the modes of operation for setprocmask.
type siginfo
type siginfo = union {
struct {
signo: signal,
errno: rt::errno,
code: int,
},
_si_pad: [128 - 3 * size(int)]u8,
};
Provides additional information about signal deliveries. Only the members
defined by POSIX are available here; cast to rt::siginfo to access
non-portable members.
TODO: Expand this with more portable options
type sigaction
Show undocumented member
type sigaction = rt::sigact;
type signal
Show undocumented member
type signal = int;
type sigset
Show undocumented member
type sigset = rt::sigset;
Constants
def SIGABRT
def SIGABRT: signal;
Process abort signal.
def SIGALRM
def SIGALRM: signal;
Alarm clock.
def SIGBUS
def SIGBUS: signal;
Access to an undefined portion of a memory object.
def SIGCHLD
def SIGCHLD: signal;
Child process terminated, stopped, or continued.
def SIGCONT
def SIGCONT: signal;
Continue executing, if stopped.
def SIGFPE
def SIGFPE: signal;
Erroneous arithmetic operation.
def SIGHUP
def SIGHUP: signal;
Hangup.
def SIGILL
def SIGILL: signal;
Illegal instruction.
def SIGINT
def SIGINT: signal;
Terminal signalerrupt signal.
def SIGIO
def SIGIO: signal;
I/O now possible.
def SIGKILL
def SIGKILL: signal;
Kill (cannot be caught or ignored).
def SIGPIPE
def SIGPIPE: signal;
Write on a pipe with no one to read it.
def SIGPOLL
def SIGPOLL: signal;
Pollable event.
def SIGPROF
def SIGPROF: signal;
Profiling timer expired.
def SIGPWR
def SIGPWR: signal;
Power failure.
def SIGQUIT
def SIGQUIT: signal;
Terminal quit signal.
def SIGSEGV
def SIGSEGV: signal;
Invalid memory reference.
def SIGSTOP
def SIGSTOP: signal;
Stop executing (cannot be caught or ignored).
def SIGSYS
def SIGSYS: signal;
Bad system call.
def SIGTERM
def SIGTERM: signal;
Termination signal.
def SIGTRAP
def SIGTRAP: signal;
Trace/breakposignal trap.
def SIGTSTP
def SIGTSTP: signal;
Terminal stop signal.
def SIGTTIN
def SIGTTIN: signal;
Background process attempting read.
def SIGTTOU
def SIGTTOU: signal;
Background process attempting write.
def SIGURG
def SIGURG: signal;
High bandwidth data is available at a socket.
def SIGUSR1
def SIGUSR1: signal;
User-defined signal 1.
def SIGUSR2
def SIGUSR2: signal;
User-defined signal 2.
def SIGVTALRM
def SIGVTALRM: signal;
Virtual timer expired.
def SIGWINCH
def SIGWINCH: signal;
Window resize signal.
def SIGXCPU
def SIGXCPU: signal;
CPU time limit exceeded.
def SIGXFSZ
def SIGXFSZ: signal;
File size limit exceeded.
Functions
fn block
fn block(signals: signal...) sigset;
Adds the given list of signals to the process's current signal mask,
returning the old signal mask. This is a convenience function around
setprocmask.
fn getprocmask
fn getprocmask() sigset;
Gets the current process's signal mask.
fn handle
fn handle(signum: signal, handler: *handler, opt: (flag | sigset)...) sigaction;
Configures a new signal handler, returning the old details (which can be
passed to restore to restore its behavior).
The variadic parameters specify either flag to enable or a signal mask
to use via sigset; if the latter is provided no more than one may be
used.
fn newsigset
fn newsigset(items: signal...) sigset;
Creates a new signal set filled in with the provided signals (or empty if
none are provided).
fn read
fn read(fd: io::file) (siginfo | errors::error);
Reads pending signal info from a signalfd.
fn restore
fn restore(signum: signal, action: *sigaction) void;
Restores previous signal behavior following handle.
fn setprocmask
fn setprocmask(how: how, mask: *sigset) sigset;
Sets the process's signal mask, returning the previous mask.
fn signalfd
fn signalfd(signals: signal...) (io::file | errors::error);
Creates a signal file that handles the given set of signals.
fn signame
fn signame(sig: signal) const str;
Returns the human friendly name of a given signal.
fn sigset_add
fn sigset_add(set: *sigset, items: signal...) void;
Adds signals to a sigset.
fn sigset_del
fn sigset_del(set: *sigset, items: signal...) void;
Removes signals from a sigset.
fn sigset_empty
fn sigset_empty(set: *sigset) void;
Sets a sigset to empty.
fn sigset_member
fn sigset_member(set: *sigset, item: signal) bool;
Returns true if the given signal is a member of this sigset.
fn unblock
fn unblock(signals: signal...) sigset;
Removes the given list of signals from the process's current signal mask,
returning the old signal mask. This is a convenience function around
setprocmask.
fn update
fn update(fd: io::file, signals: signal...) (void | errors::error);
Updates a signalfd with a new set of signals. The signal set is overwritten,
rather than appended to, with the provided set of signals.