Restore Signal::from_raw as Signal::from_named_raw. (#1406)

Rustix 1.0 moved `Signal::from_raw` into a [separate crate], since
properly supporting `SIGRTMIN+n` signals requires querying libc. But
it's still useful to have a version of this function in rustix which
is just documented to not support `SIGRTMIN+n` signals, so restore
it, with a different name and with appropriate documentation.

[separate crate]: https://crates.io/crates/rustix-libc-wrappers

Author: sunfishcode

CHANGES.md

@@ -210,6 +210,10 @@ directly convertible to `i32`; use [`Signal::as_raw`] instead.
 [`Signal::INT`]: https://docs.rs/rustix/1.0.0/rustix/process/struct.Signal.html#variant.Int
 [`Signal::as_raw`]: https://docs.rs/rustix/1.0.0/rustix/process/struct.Signal.html#method.as_raw
 
+`Signal::from_raw` is renamed to [`Signal::from_named_raw`].
+
+[`Signal::from_named_raw`]: https://docs.rs/rustix/1.0.0/rustix/process/struct.Signal.html#method.from_named_raw
+
 The associated constant `rustix::ioctl::Ioctl::OPCODE` is now replaced with an
 associated method [`rustix::ioctl::Ioctl::opcode`], to support ioctls where the
 opcode is computed rather than a constant.

src/signal.rs

@@ -255,6 +255,143 @@ impl Signal {
     pub const unsafe fn from_raw_nonzero_unchecked(sig: NonZeroI32) -> Self {
         Self(sig)
     }
+
+    /// Convert a raw named signal number into a `Signal`.
+    ///
+    /// If the given signal number corresponds to one of the named constant
+    /// signal values, such as [`Signal::HUP`] or [`Signal::INT`], return the
+    /// `Signal` value. Otherwise return `None`.
+    ///
+    /// Signals in the range `SIGRTMIN` through `SIGRTMAX` are not supported by
+    /// this function. For a constructor that does recognize those values, see
+    /// [`Signal::from_raw`] in [rustix-libc-wrappers].
+    ///
+    /// [`Signal::from_raw`]: https://docs.rs/rustix-libc-wrappers/*/rustix_libc_wrappers/trait.SignalExt.html#tymethod.from_raw
+    /// [rustix-libc-wrappers]: https://docs.rs/rustix-libc-wrappers
+    pub const fn from_named_raw(sig: i32) -> Option<Self> {
+        if let Some(sig) = NonZeroI32::new(sig) {
+            Self::from_named_raw_nonzero(sig)
+        } else {
+            None
+        }
+    }
+
+    /// Convert a raw non-zero named signal number into a `Signal`.
+    ///
+    /// If the given signal number corresponds to one of the constant signal
+    /// values, such as [`Signal::HUP`] or [`Signal::INT`], return the
+    /// `Signal` value. Otherwise return `None`.
+    ///
+    /// Signals in the range `SIGRTMIN` through `SIGRTMAX` are not supported by
+    /// this function. For a constructor that does recognize those values, see
+    /// [`Signal::from_raw_nonzero`] in [rustix-libc-wrappers].
+    ///
+    /// [`Signal::from_raw_nonzero`]: https://docs.rs/rustix-libc-wrappers/*/rustix_libc_wrappers/trait.SignalExt.html#tymethod.from_raw_nonzero
+    /// [rustix-libc-wrappers]: https://docs.rs/rustix-libc-wrappers
+    pub const fn from_named_raw_nonzero(sig: NonZeroI32) -> Option<Self> {
+        match sig.get() {
+            c::SIGHUP => Some(Self::HUP),
+            c::SIGINT => Some(Self::INT),
+            c::SIGQUIT => Some(Self::QUIT),
+            c::SIGILL => Some(Self::ILL),
+            c::SIGTRAP => Some(Self::TRAP),
+            c::SIGABRT => Some(Self::ABORT),
+            c::SIGBUS => Some(Self::BUS),
+            c::SIGFPE => Some(Self::FPE),
+            c::SIGKILL => Some(Self::KILL),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGUSR1 => Some(Self::USR1),
+            c::SIGSEGV => Some(Self::SEGV),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGUSR2 => Some(Self::USR2),
+            c::SIGPIPE => Some(Self::PIPE),
+            c::SIGALRM => Some(Self::ALARM),
+            c::SIGTERM => Some(Self::TERM),
+            #[cfg(not(any(
+                bsd,
+                solarish,
+                target_os = "aix",
+                target_os = "haiku",
+                target_os = "horizon",
+                target_os = "hurd",
+                target_os = "nto",
+                target_os = "vita",
+                all(
+                    linux_kernel,
+                    any(
+                        target_arch = "mips",
+                        target_arch = "mips32r6",
+                        target_arch = "mips64",
+                        target_arch = "mips64r6",
+                        target_arch = "sparc",
+                        target_arch = "sparc64"
+                    ),
+                )
+            )))]
+            c::SIGSTKFLT => Some(Self::STKFLT),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGCHLD => Some(Self::CHILD),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGCONT => Some(Self::CONT),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGSTOP => Some(Self::STOP),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGTSTP => Some(Self::TSTP),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGTTIN => Some(Self::TTIN),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGTTOU => Some(Self::TTOU),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGURG => Some(Self::URG),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGXCPU => Some(Self::XCPU),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGXFSZ => Some(Self::XFSZ),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGVTALRM => Some(Self::VTALARM),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGPROF => Some(Self::PROF),
+            #[cfg(not(target_os = "vita"))]
+            c::SIGWINCH => Some(Self::WINCH),
+            #[cfg(not(any(target_os = "haiku", target_os = "vita")))]
+            c::SIGIO => Some(Self::IO),
+            #[cfg(not(any(
+                bsd,
+                target_os = "haiku",
+                target_os = "horizon",
+                target_os = "hurd",
+                target_os = "vita"
+            )))]
+            c::SIGPWR => Some(Self::POWER),
+            c::SIGSYS => Some(Self::SYS),
+            #[cfg(any(
+                bsd,
+                solarish,
+                target_os = "aix",
+                target_os = "hermit",
+                all(
+                    linux_kernel,
+                    any(
+                        target_arch = "mips",
+                        target_arch = "mips32r6",
+                        target_arch = "mips64",
+                        target_arch = "mips64r6",
+                        target_arch = "sparc",
+                        target_arch = "sparc64"
+                    )
+                )
+            ))]
+            c::SIGEMT => Some(Self::EMT),
+            #[cfg(bsd)]
+            c::SIGINFO => Some(Self::INFO),
+            #[cfg(target_os = "freebsd")]
+            c::SIGTHR => Some(Self::THR),
+            #[cfg(target_os = "freebsd")]
+            c::SIGLIBRT => Some(Self::LIBRT),
+
+            _ => None,
+        }
+    }
 }
 
 impl fmt::Debug for Signal {
@@ -384,4 +521,18 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn test_named() {
+        assert_eq!(Signal::from_named_raw(-1), None);
+        assert_eq!(Signal::from_named_raw(0), None);
+        assert_eq!(Signal::from_named_raw(c::SIGHUP), Some(Signal::HUP));
+        assert_eq!(Signal::from_named_raw(c::SIGSEGV), Some(Signal::SEGV));
+        assert_eq!(Signal::from_named_raw(c::SIGSYS), Some(Signal::SYS));
+        #[cfg(any(linux_like, solarish, target_os = "hurd"))]
+        {
+            assert_eq!(Signal::from_named_raw(libc::SIGRTMIN()), None);
+            assert_eq!(Signal::from_named_raw(libc::SIGRTMAX()), None);
+        }
+    }
 }