Miscellaneous cleanups. (#1404)

Documentation:

 - Document that `rustix::buffer` is now a public API enabled by default.
 - Update comments to not say `get_` now that `get_` prefixes are removed.
 - Add `doc(cfg(feature = "alloc"))` to a few more functions.
 - Document several not_implemented functions that have been discussed
   recently.
 - Add a `#[doc(alias)]` for a renamed flag.

Misc cleanups:

 - Remove `runtime::startup_tls_info` and `runtime::StartupTlsInfo`, since
   that code [moved] to origin, and the code in rustix by now lacked some
   subsequent bug fixes.

 - Remove redundant `#[cfg(linux_raw)]`s in src/runtime.rs.

 - Add `#[must_use]` to a few private functions.

 - Remove some redundant `.as_fd()` calls.

 - Add some more special-fd-value tests.

 - Eliminate some spurious diffs between
   src/backend/linux_raw/net/addr.rs and
   src/backend/libc/net/addr.rs.

 - Add a test for `O_LARGEFILE` being non-zero.

[moved]: sunfishcode/origin#58

Author: sunfishcode

README.md

@@ -52,9 +52,9 @@ building.
 
 ## Cargo features
 
-The modules [`rustix::io`], [`rustix::fd`], [`rustix::ffi`], and
-[`rustix::ioctl`] are enabled by default. The rest of the API modules are
-conditional with cargo feature flags.
+The modules [`rustix::io`], [`rustix::buffer`], [`rustix::fd`],
+[`rustix::ffi`], and [`rustix::ioctl`] are enabled by default. The rest of the
+API modules are conditional with cargo feature flags.
 
 | Name       | Description                                                    |
 | ---------- | -------------------------------------------------------------- |

src/backend/libc/c.rs

@@ -518,3 +518,16 @@ pub(crate) use __fsid_t as fsid_t;
 #[cfg(feature = "mm")]
 #[cfg(target_os = "android")]
 pub(crate) const MAP_DROPPABLE: c_int = bitcast!(linux_raw_sys::general::MAP_DROPPABLE);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    #[cfg(linux_kernel)]
+    fn test_flags() {
+        // libc may publicly define `O_LARGEFILE` to 0, but we want the real
+        // non-zero value.
+        assert_ne!(O_LARGEFILE, 0);
+    }
+}

src/backend/libc/event/epoll.rs

@@ -66,7 +66,6 @@ bitflags! {
         const WAKEUP = bitcast!(c::EPOLLWAKEUP);
 
         /// `EPOLLEXCLUSIVE`
-        #[cfg(not(target_os = "android"))]
         const EXCLUSIVE = bitcast!(c::EPOLLEXCLUSIVE);
 
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>

src/backend/libc/fs/syscalls.rs

@@ -1283,7 +1283,7 @@ pub(crate) fn fadvise(
     // turn a very large value into a negative value.
     //
     // On FreeBSD, this could cause `posix_fadvise` to fail with
-    // `Errrno::INVAL`. Because we don't expose the signed type in our API, we
+    // `Errno::INVAL`. Because we don't expose the signed type in our API, we
     // also avoid exposing this artifact of casting an unsigned value to the
     // signed type. To do this, we use a no-op call in this case.
     //
@@ -1298,7 +1298,7 @@ pub(crate) fn fadvise(
 
         #[cold]
         fn fadvise_noop(fd: BorrowedFd<'_>) -> io::Result<()> {
-            // Us an `fcntl` to report `Errno::EBADF` if needed, but otherwise
+            // Use an `fcntl` to report `Errno::BADF` if needed, but otherwise
             // do nothing.
             fcntl_getfl(fd).map(|_| ())
         }

src/backend/libc/net/addr.rs

@@ -140,8 +140,8 @@ impl SocketAddrUnix {
         let bytes = self.bytes()?;
         if !bytes.is_empty() && bytes[0] != 0 {
             if self.unix.sun_path.len() == bytes.len() {
-                // SAFETY: no NULs are contained in bytes
-                unsafe { self.path_with_termination(bytes) }
+                // SAFETY: There are no NULs contained in bytes.
+                unsafe { Self::path_with_termination(bytes) }
             } else {
                 // SAFETY: `from_bytes_with_nul_unchecked` since the string is
                 // NUL-terminated.
@@ -154,9 +154,10 @@ impl SocketAddrUnix {
 
     /// If the `sun_path` field is not NUL-terminated, terminate it.
     ///
-    /// SAFETY: the input `bytes` must not contain any NULs
+    /// SAFETY: The input `bytes` must not contain any NULs.
     #[cfg(feature = "alloc")]
-    unsafe fn path_with_termination(&self, bytes: &[u8]) -> Option<Cow<'_, CStr>> {
+    #[cold]
+    unsafe fn path_with_termination(bytes: &[u8]) -> Option<Cow<'_, CStr>> {
         let mut owned = Vec::with_capacity(bytes.len() + 1);
         owned.extend_from_slice(bytes);
         owned.push(b'\0');

src/backend/linux_raw/fs/syscalls.rs

@@ -22,14 +22,6 @@ use crate::backend::conv::{
 };
 #[cfg(target_pointer_width = "64")]
 use crate::backend::conv::{loff_t, loff_t_from_u64, ret_u64};
-#[cfg(any(
-    target_arch = "aarch64",
-    target_arch = "riscv64",
-    target_arch = "mips64",
-    target_arch = "mips64r6",
-    target_pointer_width = "32",
-))]
-use crate::fd::AsFd;
 use crate::fd::{BorrowedFd, OwnedFd};
 use crate::ffi::CStr;
 #[cfg(any(target_arch = "aarch64", target_arch = "riscv64"))]
@@ -62,7 +54,7 @@ pub(crate) fn open(path: &CStr, flags: OFlags, mode: Mode) -> io::Result<OwnedFd
 
     #[cfg(any(target_arch = "aarch64", target_arch = "riscv64"))]
     {
-        openat(CWD.as_fd(), path, flags, mode)
+        openat(CWD, path, flags, mode)
     }
     #[cfg(not(any(target_arch = "aarch64", target_arch = "riscv64")))]
     unsafe {
@@ -552,7 +544,7 @@ pub(crate) fn stat(path: &CStr) -> io::Result<Stat> {
     ))]
     {
         match crate::fs::statx(
-            crate::fs::CWD.as_fd(),
+            crate::fs::CWD,
             path,
             AtFlags::empty(),
             StatxFlags::BASIC_STATS,
@@ -669,7 +661,7 @@ pub(crate) fn lstat(path: &CStr) -> io::Result<Stat> {
     #[cfg(any(target_pointer_width = "32", target_arch = "mips64"))]
     {
         match crate::fs::statx(
-            crate::fs::CWD.as_fd(),
+            crate::fs::CWD,
             path,
             AtFlags::SYMLINK_NOFOLLOW,
             StatxFlags::BASIC_STATS,
@@ -1393,7 +1385,7 @@ pub(crate) fn futimens(fd: BorrowedFd<'_>, times: &Timestamps) -> io::Result<()>
 pub(crate) fn access(path: &CStr, access: Access) -> io::Result<()> {
     #[cfg(any(target_arch = "aarch64", target_arch = "riscv64"))]
     {
-        accessat_noflags(CWD.as_fd(), path, access)
+        accessat_noflags(CWD, path, access)
     }
 
     #[cfg(not(any(target_arch = "aarch64", target_arch = "riscv64")))]

src/backend/linux_raw/net/addr.rs

@@ -102,7 +102,7 @@ impl SocketAddrUnix {
         let bytes = self.bytes()?;
         if !bytes.is_empty() && bytes[0] != 0 {
             if self.unix.sun_path.len() == bytes.len() {
-                // SAFETY: no NULs are contained in bytes
+                // SAFETY: There are no NULs contained in bytes.
                 unsafe { Self::path_with_termination(bytes) }
             } else {
                 // SAFETY: `from_bytes_with_nul_unchecked` since the string is
@@ -116,7 +116,7 @@ impl SocketAddrUnix {
 
     /// If the `sun_path` field is not NUL-terminated, terminate it.
     ///
-    /// SAFETY: the input `bytes` must not contain any NULs
+    /// SAFETY: The input `bytes` must not contain any NULs.
     #[cfg(feature = "alloc")]
     #[cold]
     unsafe fn path_with_termination(bytes: &[u8]) -> Option<Cow<'_, CStr>> {

src/backend/linux_raw/pid/syscalls.rs

@@ -9,6 +9,7 @@ use crate::backend::conv::ret_usize_infallible;
 use crate::pid::{Pid, RawPid};
 
 #[inline]
+#[must_use]
 pub(crate) fn getpid() -> Pid {
     unsafe {
         let pid = ret_usize_infallible(syscall_readonly!(__NR_getpid)) as RawPid;

src/backend/linux_raw/process/syscalls.rs

@@ -58,6 +58,7 @@ pub(crate) fn getcwd(buf: &mut [MaybeUninit<u8>]) -> io::Result<usize> {
 }
 
 #[inline]
+#[must_use]
 pub(crate) fn getppid() -> Option<Pid> {
     unsafe {
         let ppid = ret_c_int_infallible(syscall_readonly!(__NR_getppid));
@@ -86,6 +87,7 @@ pub(crate) fn setpgid(pid: Option<Pid>, pgid: Option<Pid>) -> io::Result<()> {
 }
 
 #[inline]
+#[must_use]
 pub(crate) fn getpgrp() -> Pid {
     // Use the `getpgrp` syscall if available.
     #[cfg(not(any(target_arch = "aarch64", target_arch = "riscv64")))]

src/backend/linux_raw/runtime/tls.rs

@@ -1,98 +1,7 @@
 //! TLS utilities.
-//!
-//! # Safety
-//!
-//! This file contains code that reads the raw phdr array pointed to by the
-//! kernel-provided AUXV values.
-#![allow(unsafe_code)]
-
-use crate::backend::c;
-use crate::backend::param::auxv::exe_phdrs;
-use core::arch::global_asm;
-use core::ptr::{null, NonNull};
-use linux_raw_sys::elf::*;
 
 /// For use with [`set_thread_area`].
 ///
 /// [`set_thread_area`]: crate::runtime::set_thread_area
 #[cfg(target_arch = "x86")]
 pub type UserDesc = linux_raw_sys::general::user_desc;
-
-pub(crate) fn startup_tls_info() -> StartupTlsInfo {
-    let mut base = null();
-    let mut tls_phdr = null();
-    let mut stack_size = 0;
-
-    let (first_phdr, phent, phnum) = exe_phdrs();
-    let mut current_phdr = first_phdr.cast::<Elf_Phdr>();
-
-    // The dynamic address of the dynamic section, which we can compare with
-    // the `PT_DYNAMIC` header's static address, if present.
-    let dynamic_addr: *const c::c_void = unsafe { &_DYNAMIC };
-
-    // SAFETY: We assume the phdr array pointer and length the kernel provided
-    // to the process describe a valid phdr array.
-    unsafe {
-        let phdrs_end = current_phdr.cast::<u8>().add(phnum * phent).cast();
-        while current_phdr != phdrs_end {
-            let phdr = &*current_phdr;
-            current_phdr = current_phdr.cast::<u8>().add(phent).cast();
-
-            match phdr.p_type {
-                // Compute the offset from the static virtual addresses
-                // in the `p_vaddr` fields to the dynamic addresses. We don't
-                // always get a `PT_PHDR` or `PT_DYNAMIC` header, so use
-                // whichever one we get.
-                PT_PHDR => base = first_phdr.cast::<u8>().wrapping_sub(phdr.p_vaddr),
-                PT_DYNAMIC => base = dynamic_addr.cast::<u8>().wrapping_sub(phdr.p_vaddr),
-
-                PT_TLS => tls_phdr = phdr,
-                PT_GNU_STACK => stack_size = phdr.p_memsz,
-                _ => {}
-            }
-        }
-
-        if tls_phdr.is_null() {
-            StartupTlsInfo {
-                addr: NonNull::dangling().as_ptr(),
-                mem_size: 0,
-                file_size: 0,
-                align: 1,
-                stack_size: 0,
-            }
-        } else {
-            StartupTlsInfo {
-                addr: base.cast::<u8>().wrapping_add((*tls_phdr).p_vaddr).cast(),
-                mem_size: (*tls_phdr).p_memsz,
-                file_size: (*tls_phdr).p_filesz,
-                align: (*tls_phdr).p_align,
-                stack_size,
-            }
-        }
-    }
-}
-
-extern "C" {
-    /// Declare the `_DYNAMIC` symbol so that we can compare its address with
-    /// the static address in the `PT_DYNAMIC` header to learn our offset. Use
-    /// a weak symbol because `_DYNAMIC` is not always present.
-    static _DYNAMIC: c::c_void;
-}
-// Rust has `extern_weak` but it isn't stable, so use a `global_asm`.
-global_asm!(".weak _DYNAMIC");
-
-/// The values returned from [`startup_tls_info`].
-///
-/// [`startup_tls_info`]: crate::runtime::startup_tls_info
-pub struct StartupTlsInfo {
-    /// The base address of the TLS segment.
-    pub addr: *const c::c_void,
-    /// The size of the memory region.
-    pub mem_size: usize,
-    /// The size beyond which all memory is zero-initialized.
-    pub file_size: usize,
-    /// The required alignment for the TLS segment.
-    pub align: usize,
-    /// The requested minimum size for stacks.
-    pub stack_size: usize,
-}