documentation & doctests for signal handling utils

Signed-off-by: Alexandra Iordache <[email protected]>

Author: Alexandra Iordache

sys_util/src/signal.rs

@@ -36,13 +36,25 @@ fn SIGRTMAX() -> c_int {
     unsafe { __libc_current_sigrtmax() }
 }
 
-/// Verifies that a signal number is valid.
+/// Verifies that a signal number is valid when sent to a vCPU.
 ///
 /// VCPU signals need to have values enclosed within the OS limits for realtime signals.
+/// Returns either `Ok(num)` or `Err(EINVAL)`.
 ///
-/// Will return Ok(num) or Err(EINVAL).
-pub fn validate_vcpu_signal_num(num: c_int) -> io::Result<c_int> {
-    let actual_num = num + SIGRTMIN();
+/// # Arguments
+///
+/// * `signum`: signal number.
+///
+/// # Example
+///
+/// ```
+/// use sys_util::validate_vcpu_signal_num;
+/// assert!(validate_vcpu_signal_num(0).is_ok());
+/// assert!(validate_vcpu_signal_num(32).is_err());
+/// ```
+///
+pub fn validate_vcpu_signal_num(signum: c_int) -> io::Result<c_int> {
+    let actual_num = signum + SIGRTMIN();
     if actual_num <= SIGRTMAX() {
         Ok(actual_num)
     } else {
@@ -54,6 +66,34 @@ pub fn validate_vcpu_signal_num(num: c_int) -> io::Result<c_int> {
 ///
 /// This is considered unsafe because the given handler will be called asynchronously, interrupting
 /// whatever the thread was doing and therefore must only do async-signal-safe operations.
+///
+/// # Arguments
+///
+/// * `signum`: signal number.
+/// * `handler`: signal handler functor.
+///
+/// # Example
+///
+/// ```
+/// extern crate libc;
+/// extern crate sys_util;
+///
+/// use libc::{c_int, c_void, raise, siginfo_t};
+/// use sys_util::register_vcpu_signal_handler;
+///
+/// extern "C" fn handle_signal(_: c_int, _: *mut siginfo_t, _: *mut c_void) {}
+/// extern "C" { fn __libc_current_sigrtmin() -> c_int; }
+///
+/// fn main() {
+///     // Register dummy signal handler for `SIGRTMIN`.
+///     assert!(unsafe { register_vcpu_signal_handler(0, handle_signal).is_ok() });
+///     // Raise `SIGRTMIN`.
+///     unsafe { raise(__libc_current_sigrtmin()); }
+///     // Assert that the process is still alive.
+///     assert!(true);
+/// }
+/// ```
+///
 pub unsafe fn register_vcpu_signal_handler(
     signum: c_int,
     handler: SignalHandler,
@@ -67,6 +107,34 @@ pub unsafe fn register_vcpu_signal_handler(
 }
 
 /// Registers `handler` as the process' signal handler of `signum`.
+///
+/// # Arguments
+///
+/// * `signum`: signal number.
+/// * `handler`: signal handler functor.
+///
+/// # Example
+///
+/// ```
+/// extern crate libc;
+/// extern crate sys_util;
+///
+/// use std::sync::atomic::{AtomicBool, Ordering, ATOMIC_BOOL_INIT};
+/// use libc::{c_int, c_void, raise, siginfo_t, SIGUSR1};
+/// use sys_util::register_signal_handler;
+///
+/// static HANDLER_CALLED: AtomicBool = ATOMIC_BOOL_INIT;
+/// extern "C" fn handle_signal(_: c_int, _: *mut siginfo_t, _: *mut c_void) {
+///     HANDLER_CALLED.store(true, Ordering::SeqCst);
+/// }
+///
+/// fn main() {
+///     assert!(unsafe { register_signal_handler(SIGUSR1, handle_signal).is_ok() });
+///     unsafe { raise(SIGUSR1); }
+///     assert!(HANDLER_CALLED.load(Ordering::SeqCst));
+/// }
+/// ```
+///
 pub fn register_signal_handler(signum: c_int, handler: SignalHandler) -> Result<(), io::Error> {
     // Safe, because this is a POD struct.
     let mut sigact: sigaction = unsafe { mem::zeroed() };

vmm/src/signal_handler.rs

@@ -21,6 +21,11 @@ const SI_OFF_SYSCALL: isize = 6;
 
 const SYS_SECCOMP_CODE: i32 = 1;
 
+/// Signal handler for `SIGSYS`.
+///
+/// Increments the `seccomp.num_faults` metric, logs an error message and terminates the process
+/// with a specific exit code.
+///
 extern "C" fn sigsys_handler(num: c_int, info: *mut siginfo_t, _unused: *mut c_void) {
     // Safe because we're just reading some fields from a supposedly valid argument.
     let si_signo = unsafe { (*info).si_signo };
@@ -53,6 +58,10 @@ extern "C" fn sigsys_handler(num: c_int, info: *mut siginfo_t, _unused: *mut c_v
     };
 }
 
+/// Signal handler for `SIGBUS` and `SIGSEGV`.
+///
+/// Logs an error message and terminates the process with a specific exit code.
+///
 extern "C" fn sigbus_sigsegv_handler(num: c_int, info: *mut siginfo_t, _unused: *mut c_void) {
     // Safe because we're just reading some fields from a supposedly valid argument.
     let si_signo = unsafe { (*info).si_signo };