Miscellaneous cleanups (#672)

* Miscellaneous cleanups

 - Add more comments.
 - Fix a few clippy lints.

* Define `SIGEMT` on more platforms.

* Mark `sigwait` etc. as `unsafe`.

* Use `CLOEXEC` in code examples that call `openat`.

Author: sunfishcode

build.rs

@@ -82,9 +82,10 @@ fn main() {
         use_feature("linux_raw");
         use_feature_or_nothing("core_intrinsics");
 
-        // Use inline asm if we have it, or outline asm otherwise. On PowerPC
-        // and MIPS, Rust's inline asm is considered experimental, so only use
-        // it if `--cfg=rustix_use_experimental_asm` is given.
+        // Use inline asm if we have it, or outline asm otherwise. On 32-bit
+        // x86 our asm support requires naked functions. On PowerPC and MIPS,
+        // Rust's inline asm is considered experimental, so only use it if
+        // `--cfg=rustix_use_experimental_asm` is given.
         if (feature_rustc_dep_of_std || vendor == "mustang" || can_compile("use std::arch::asm;"))
             && (arch != "x86" || has_feature("naked_functions"))
             && ((arch != "powerpc64" && arch != "mips" && arch != "mips64")

examples/kq.rs

@@ -10,7 +10,12 @@ fn main() -> std::io::Result<()> {
     let mut out = Vec::with_capacity(10);
 
     #[cfg(feature = "fs")]
-    let dir = fs::openat(fs::cwd(), ".", fs::OFlags::DIRECTORY, fs::Mode::empty())?;
+    let dir = fs::openat(
+        fs::cwd(),
+        ".",
+        fs::OFlags::RDONLY | fs::OFlags::DIRECTORY | fs::OFlags::CLOEXEC,
+        fs::Mode::empty(),
+    )?;
 
     let subs = [
         #[cfg(feature = "process")]

src/backend/libc/process/types.rs

@@ -205,8 +205,19 @@ pub enum Signal {
     #[doc(alias = "Unused")]
     Sys = c::SIGSYS,
     /// `SIGEMT`
-    #[cfg(bsd)]
+    #[cfg(any(bsd, solarish, target_os = "aix", target_os = "hermit",))]
     Emt = c::SIGEMT,
+    /// `SIGEMT`
+    #[cfg(all(
+        any(target_os = "android", target_os = "linux"),
+        any(
+            target_arch = "mips",
+            target_arch = "mips64",
+            target_arch = "sparc",
+            target_arch = "sparc64"
+        )
+    ))]
+    Emt = linux_raw_sys::general::SIGEMT as i32,
     /// `SIGINFO`
     #[cfg(bsd)]
     Info = c::SIGINFO,

src/backend/linux_raw/net/addr.rs

@@ -55,7 +55,7 @@ impl SocketAddrUnix {
             let len = len.try_into().unwrap();
             Ok(Self { unix, len })
         } else {
-            return Err(io::Errno::NAMETOOLONG);
+            Err(io::Errno::NAMETOOLONG)
         }
     }
 

src/backend/linux_raw/process/types.rs

@@ -104,6 +104,14 @@ pub enum Signal {
     #[doc(alias = "Iot")]
     #[doc(alias = "Abrt")]
     Abort = linux_raw_sys::general::SIGABRT,
+    /// `SIGEMT`
+    #[cfg(any(
+        target_arch = "mips",
+        target_arch = "mips64",
+        target_arch = "sparc",
+        target_arch = "sparc64"
+    ))]
+    Emt = linux_raw_sys::general::SIGEMT,
     /// `SIGBUS`
     Bus = linux_raw_sys::general::SIGBUS,
     /// `SIGFPE`

src/fs/raw_dir.rs

@@ -45,7 +45,13 @@ impl<'buf, Fd: AsFd> RawDir<'buf, Fd> {
     /// # use std::mem::MaybeUninit;
     /// # use rustix::fs::{cwd, Mode, OFlags, openat, RawDir};
     ///
-    /// let fd = openat(cwd(), ".", OFlags::RDONLY | OFlags::DIRECTORY, Mode::empty()).unwrap();
+    /// let fd = openat(
+    ///     cwd(),
+    ///     ".",
+    ///     OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
+    ///     Mode::empty(),
+    /// )
+    /// .unwrap();
     ///
     /// let mut buf = Vec::with_capacity(8192);
     /// let mut iter = RawDir::new(fd, buf.spare_capacity_mut());
@@ -64,7 +70,7 @@ impl<'buf, Fd: AsFd> RawDir<'buf, Fd> {
     /// let fd = openat(
     ///     cwd(),
     ///     ".",
-    ///     OFlags::RDONLY | OFlags::DIRECTORY,
+    ///     OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
     ///     Mode::empty(),
     /// )
     /// .unwrap();
@@ -88,7 +94,13 @@ impl<'buf, Fd: AsFd> RawDir<'buf, Fd> {
     /// # use rustix::fs::{cwd, Mode, OFlags, openat, RawDir};
     /// # use rustix::io::Errno;
     ///
-    /// let fd = openat(cwd(), ".", OFlags::RDONLY | OFlags::DIRECTORY, Mode::empty()).unwrap();
+    /// let fd = openat(
+    ///     cwd(),
+    ///     ".",
+    ///     OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
+    ///     Mode::empty(),
+    /// )
+    /// .unwrap();
     ///
     /// let mut buf = Vec::with_capacity(8192);
     /// 'read: loop {

src/lib.rs

@@ -59,6 +59,8 @@
 //!  - Constants use `enum`s and [`bitflags`] types.
 //!  - Multiplexed functions (eg. `fcntl`, `ioctl`, etc.) are de-multiplexed.
 //!  - Variadic functions (eg. `openat`, etc.) are presented as non-variadic.
+//!  - Functions that return strings automatically allocate sufficient memory
+//!    and retry the syscall as needed to determine the needed length.
 //!  - Functions and types which need `l` prefixes or `64` suffixes to enable
 //!    large-file support (LFS) are used automatically. File sizes and offsets
 //!    are always presented as `u64` and `i64`.
@@ -109,10 +111,9 @@
 #![cfg_attr(alloc_c_string, feature(alloc_ffi))]
 #![cfg_attr(alloc_c_string, feature(alloc_c_string))]
 #![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(feature = "rustc-dep-of-std", feature(core_intrinsics))]
 #![cfg_attr(feature = "rustc-dep-of-std", feature(ip))]
 #![cfg_attr(
-    all(not(feature = "rustc-dep-of-std"), core_intrinsics),
+    any(feature = "rustc-dep-of-std", core_intrinsics),
     feature(core_intrinsics)
 )]
 #![cfg_attr(asm_experimental_arch, feature(asm_experimental_arch))]

src/runtime.rs

@@ -85,13 +85,25 @@ pub unsafe fn arm_set_tls(data: *mut c_void) -> io::Result<()> {
     backend::runtime::syscalls::tls::arm_set_tls(data)
 }
 
+/// `prctl(PR_SET_FS, data)`—Set the x86_64 `fs` register.
+///
+/// # Safety
+///
+/// This is a very low-level feature for implementing threading libraries.
+/// See the references links above.
 #[cfg(linux_raw)]
 #[cfg(target_arch = "x86_64")]
 #[inline]
 pub unsafe fn set_fs(data: *mut c_void) {
     backend::runtime::syscalls::tls::set_fs(data)
 }
 
+/// Set the x86_64 thread ID address.
+///
+/// # Safety
+///
+/// This is a very low-level feature for implementing threading libraries.
+/// See the references links above.
 #[cfg(linux_raw)]
 #[inline]
 pub unsafe fn set_tid_address(data: *mut c_void) -> Pid {
@@ -384,36 +396,54 @@ pub unsafe fn sigprocmask(how: How, set: Option<&Sigset>) -> io::Result<Sigset>
 
 /// `sigwait(set)`—Wait for signals.
 ///
+/// # Safety
+///
+/// If code elsewhere in the process is depending on delivery of a signal to
+/// prevent it from executing some code, this could cause it to miss that
+/// signal and execute that code.
+///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man3/sigwait.3.html
 #[cfg(linux_raw)]
 #[inline]
-pub fn sigwait(set: &Sigset) -> io::Result<Signal> {
+pub unsafe fn sigwait(set: &Sigset) -> io::Result<Signal> {
     backend::runtime::syscalls::sigwait(set)
 }
 
 /// `sigwait(set)`—Wait for signals, returning a [`Siginfo`].
 ///
+/// # Safety
+///
+/// If code elsewhere in the process is depending on delivery of a signal to
+/// prevent it from executing some code, this could cause it to miss that
+/// signal and execute that code.
+///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/sigwaitinfo.2.html
 #[cfg(linux_raw)]
 #[inline]
-pub fn sigwaitinfo(set: &Sigset) -> io::Result<Siginfo> {
+pub unsafe fn sigwaitinfo(set: &Sigset) -> io::Result<Siginfo> {
     backend::runtime::syscalls::sigwaitinfo(set)
 }
 
 /// `sigtimedwait(set)`—Wait for signals, optionally with a timeout.
 ///
+/// # Safety
+///
+/// If code elsewhere in the process is depending on delivery of a signal to
+/// prevent it from executing some code, this could cause it to miss that
+/// signal and execute that code.
+///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/sigtimedwait.2.html
 #[cfg(linux_raw)]
 #[inline]
-pub fn sigtimedwait(set: &Sigset, timeout: Option<Timespec>) -> io::Result<Siginfo> {
+pub unsafe fn sigtimedwait(set: &Sigset, timeout: Option<Timespec>) -> io::Result<Siginfo> {
     backend::runtime::syscalls::sigtimedwait(set, timeout)
 }

src/termios/tty.rs

@@ -1,18 +1,11 @@
 //! Functions which operate on file descriptors which might be terminals.
 
 use crate::backend;
-#[cfg(any(
-    all(linux_raw, feature = "procfs"),
-    all(libc, not(any(target_os = "fuchsia", target_os = "wasi"))),
-))]
-use crate::io;
 use backend::fd::AsFd;
-#[cfg(any(
-    all(linux_raw, feature = "procfs"),
-    all(libc, not(any(target_os = "fuchsia", target_os = "wasi"))),
-))]
+#[cfg(feature = "procfs")]
+#[cfg(not(any(target_os = "fuchsia", target_os = "wasi")))]
 use {
-    crate::ffi::CString, crate::path::SMALL_PATH_BUFFER_SIZE, alloc::vec::Vec,
+    crate::ffi::CString, crate::io, crate::path::SMALL_PATH_BUFFER_SIZE, alloc::vec::Vec,
     backend::fd::BorrowedFd,
 };
 

tests/fs/makedev.rs

@@ -2,7 +2,7 @@ use rustix::fs::{major, makedev, minor};
 
 #[test]
 fn makedev_roundtrip() {
-    // Apple's, FreeBSD 11's, and Dragonfly's `makedev` doesn't handle extra
+    // Apple's, FreeBSD 11's, and DragonFly's `makedev` doesn't handle extra
     // bits set.
     #[cfg(freebsdlike)]
     let (maj, min) = (0x0000_0026, 0x6564_0061);