pub unsafe fn register<F>(signal: c_int, action: F) -> Result<SigId, Error>
Expand description
Registers an arbitrary action for the given signal.
This makes sure there’s a signal handler for the given signal. It then adds the action to the ones called each time the signal is delivered. If multiple actions are set for the same signal, all are called, in the order of registration.
If there was a previous signal handler for the given signal, it is chained ‒ it will be called as part of this library’s signal handler, before any actions set through this function.
On success, the function returns an ID that can be used to remove the action again with
unregister
.
§Panics
If the signal is one of (see FORBIDDEN
):
SIGKILL
SIGSTOP
SIGILL
SIGFPE
SIGSEGV
The first two are not possible to override (and the underlying C functions simply ignore all
requests to do so, which smells of possible bugs, or return errors). The rest can be set, but
generally needs very special handling to do so correctly (direct manipulation of the
application’s address space, longjmp
and similar). Unless you know very well what you’re
doing, you’ll shoot yourself into the foot and this library won’t help you with that.
§Errors
Since the library manipulates signals using the low-level C functions, all these can return errors. Generally, the errors mean something like the specified signal does not exist on the given platform ‒ after a program is debugged and tested on a given OS, it should never return an error.
However, if an error is returned, there are no guarantees if the given action was registered or not.
§Safety
This function is unsafe, because the action
is run inside a signal handler. The set of
functions allowed to be called from within is very limited (they are called async-signal-safe
functions by POSIX). These specifically do not contain mutexes and memory
allocation/deallocation. They do contain routines to terminate the program, to further
manipulate signals (by the low-level functions, not by this library) and to read and write file
descriptors. Calling program’s own functions consisting only of these is OK, as is manipulating
program’s variables ‒ however, as the action can be called on any thread that does not have the
given signal masked (by default no signal is masked on any thread), and mutexes are a no-go,
this is harder than it looks like at first.
As panicking from within a signal handler would be a panic across FFI boundary (which is undefined behavior), the passed handler must not panic.
If you find these limitations hard to satisfy, choose from the helper functions in the signal-hook crate ‒ these provide safe interface to use some common signal handling patters.
§Race condition
Upon registering the first hook for a given signal into this library, there’s a short race condition under the following circumstances:
- The program already has a signal handler installed for this particular signal (through some other library, possibly).
- Concurrently, some other thread installs a different signal handler while it is being installed by this library.
- At the same time, the signal is delivered.
Under such conditions signal-hook might wrongly “chain” to the older signal handler for a short while (until the registration is fully complete).
Note that the exact conditions of the race condition might change in future versions of the library. The recommended way to avoid it is to register signals before starting any additional threads, or at least not to register signals concurrently.
Alternatively, make sure all signals are handled through this library.
§Performance
Even when it is possible to repeatedly install and remove actions during the lifetime of a
program, the installation and removal is considered a slow operation and should not be done
very often. Also, there’s limited (though huge) amount of distinct IDs (they are u128
).
§Examples
extern crate signal_hook_registry;
use std::io::Error;
use std::process;
fn main() -> Result<(), Error> {
let signal = unsafe {
signal_hook_registry::register(signal_hook::consts::SIGTERM, || process::abort())
}?;
// Stuff here...
signal_hook_registry::unregister(signal); // Not really necessary.
Ok(())
}