Miscellaneous documentation and clippy fixes. (#1354)

sunfishcode · web-flow · commit f3205ddd1599 · 2025-02-26T07:58:11.000-08:00
diff --git a/benches/mod.rs b/benches/mod.rs
@@ -20,8 +20,8 @@
 ))]
 fn main() {
     unimplemented!(
-        "Add --cfg=criterion to RUSTFLAGS and enable the \"fs\", \"time\", \"process\", and \"stdio\" cargo \
-         features."
+        "Add --cfg=criterion to RUSTFLAGS and enable the \"fs\", \"time\", \"process\", and \
+         \"stdio\" cargo features."
     )
 }
 
diff --git a/src/backend/libc/c.rs b/src/backend/libc/c.rs
@@ -258,7 +258,8 @@ mod readwrite_pv64 {
             fun(fd, iov, iovcnt, offset)
         } else {
             // Unlike the plain "p" functions, the "pv" functions pass their
-            // offset in an endian-independent way, and always in two registers.
+            // offset in an endian-independent way, and always in two
+            // registers.
             syscall! {
                 fn preadv(
                     fd: c_int,
@@ -285,7 +286,8 @@ mod readwrite_pv64 {
             fun(fd, iov, iovcnt, offset)
         } else {
             // Unlike the plain "p" functions, the "pv" functions pass their
-            // offset in an endian-independent way, and always in two registers.
+            // offset in an endian-independent way, and always in two
+            // registers.
             syscall! {
                 fn pwritev(
                     fd: c_int,
@@ -348,7 +350,8 @@ mod readwrite_pv64v2 {
             fun(fd, iov, iovcnt, offset, flags)
         } else {
             // Unlike the plain "p" functions, the "pv" functions pass their
-            // offset in an endian-independent way, and always in two registers.
+            // offset in an endian-independent way, and always in two
+            // registers.
             syscall! {
                 fn preadv2(
                     fd: c_int,
@@ -384,7 +387,8 @@ mod readwrite_pv64v2 {
             fun(fd, iov, iovcnt, offset, flags)
         } else {
             // Unlike the plain "p" functions, the "pv" functions pass their
-            // offset in an endian-independent way, and always in two registers.
+            // offset in an endian-independent way, and always in two
+            // registers.
             syscall! {
                 fn pwritev2(
                     fd: c_int,
diff --git a/src/backend/libc/fs/dir.rs b/src/backend/libc/fs/dir.rs
@@ -154,7 +154,8 @@ impl Dir {
 
     /// `readdir(self)`, where `None` means the end of the directory.
     pub fn read(&mut self) -> Option<io::Result<DirEntry>> {
-        // If we've seen errors, don't continue to try to read anything further.
+        // If we've seen errors, don't continue to try to read anything
+        // further.
         if self.any_errors {
             return None;
         }
diff --git a/src/backend/libc/net/addr.rs b/src/backend/libc/net/addr.rs
@@ -125,7 +125,8 @@ impl SocketAddrUnix {
     pub fn path(&self) -> Option<&CStr> {
         let bytes = self.bytes()?;
         if !bytes.is_empty() && bytes[0] != 0 {
-            // SAFETY: `from_bytes_with_nul_unchecked` since the string is NUL-terminated.
+            // SAFETY: `from_bytes_with_nul_unchecked` since the string is
+            // NUL-terminated.
             Some(unsafe { CStr::from_bytes_with_nul_unchecked(bytes) })
         } else {
             None
diff --git a/src/backend/libc/process/syscalls.rs b/src/backend/libc/process/syscalls.rs
@@ -669,7 +669,8 @@ pub(crate) fn fcntl_getlk(fd: BorrowedFd<'_>, lock: &Flock) -> io::Result<Option
     let mut curr_lock: c::flock = lock.as_raw();
     unsafe { ret(c::fcntl(borrowed_fd(fd), c::F_GETLK, &mut curr_lock))? };
 
-    // If no blocking lock is found, `fcntl(GETLK, ..)` sets `l_type` to `F_UNLCK`
+    // If no blocking lock is found, `fcntl(GETLK, ..)` sets `l_type` to
+    // `F_UNLCK`.
     if curr_lock.l_type == c::F_UNLCK as _ {
         Ok(None)
     } else {
diff --git a/src/backend/linux_raw/fs/dir.rs b/src/backend/linux_raw/fs/dir.rs
@@ -110,7 +110,8 @@ impl Dir {
 
     /// `readdir(self)`, where `None` means the end of the directory.
     pub fn read(&mut self) -> Option<io::Result<DirEntry>> {
-        // If we've seen errors, don't continue to try to read anything further.
+        // If we've seen errors, don't continue to try to read anything
+        // further.
         if self.any_errors {
             return None;
         }
diff --git a/src/backend/linux_raw/net/addr.rs b/src/backend/linux_raw/net/addr.rs
@@ -94,7 +94,8 @@ impl SocketAddrUnix {
     pub fn path(&self) -> Option<&CStr> {
         let bytes = self.bytes()?;
         if !bytes.is_empty() && bytes[0] != 0 {
-            // SAFETY: `from_bytes_with_nul_unchecked` since the string is NUL-terminated.
+            // SAFETY: `from_bytes_with_nul_unchecked` since the string is
+            // NUL-terminated.
             Some(unsafe { CStr::from_bytes_with_nul_unchecked(bytes) })
         } else {
             None
diff --git a/src/backend/linux_raw/process/syscalls.rs b/src/backend/linux_raw/process/syscalls.rs
@@ -548,7 +548,8 @@ pub(crate) fn fcntl_getlk(fd: BorrowedFd<'_>, lock: &Flock) -> io::Result<Option
         ))?
     }
 
-    // If no blocking lock is found, `fcntl(GETLK, ..)` sets `l_type` to `F_UNLCK`
+    // If no blocking lock is found, `fcntl(GETLK, ..)` sets `l_type` to
+    // `F_UNLCK`.
     if curr_lock.l_type == c::F_UNLCK as _ {
         Ok(None)
     } else {
diff --git a/src/backend/linux_raw/vdso.rs b/src/backend/linux_raw/vdso.rs
@@ -218,8 +218,8 @@ fn init_from_sysinfo_ehdr() -> Option<Vdso> {
         // Parse the hash table header.
         if !vdso.gnu_hash.is_null() {
             vdso.nbucket = ElfHashEntry::from(*vdso.gnu_hash);
-            // The bucket array is located after the header (4 uint32) and the bloom
-            // filter (size_t array of gnu_hash[2] elements).
+            // The bucket array is located after the header (4 uint32) and the
+            // bloom filter (size_t array of gnu_hash[2] elements).
             vdso.bucket = vdso
                 .gnu_hash
                 .add(4)
@@ -497,6 +497,8 @@ fn test_vdso() {
         #[cfg(any(target_arch = "mips64", target_arch = "mips64r6"))]
         let ptr = vdso.sym(cstr!("LINUX_2.6"), cstr!("__vdso_gettimeofday"));
 
+        // On PowerPC, "__kernel_clock_gettime64" isn't available in
+        // Linux < 5.11.
         #[cfg(not(target_arch = "powerpc"))]
         assert!(!ptr.is_null());
     }
diff --git a/src/fs/constants.rs b/src/fs/constants.rs
@@ -20,7 +20,8 @@ mod tests {
         #[cfg(linux_kernel)]
         assert_eq_size!(FsWord, linux_raw_sys::general::__fsword_t);
 
-        // Don't test against `__kernel_mode_t` on platforms where it's a `u16`.
+        // Don't test against `__kernel_mode_t` on platforms where it's a
+        // `u16`.
         #[cfg(linux_kernel)]
         #[cfg(not(any(
             target_arch = "x86",
diff --git a/src/fs/xattr.rs b/src/fs/xattr.rs
@@ -1,3 +1,5 @@
+//! Extended attribute functions.
+
 #![allow(unsafe_code)]
 
 use crate::buffer::Buffer;
diff --git a/src/ioctl/linux.rs b/src/ioctl/linux.rs
@@ -106,8 +106,6 @@ fn check_known_opcodes() {
     );
 
     // _IOW('v', 2, long)
-    // This constant is currently incorrectly defined on PowerPC,
-    // see https://github.com/sunfishcode/linux-raw-sys/issues/148
     assert_eq!(
         compose_opcode(
             Direction::Write,
diff --git a/src/ioctl/patterns.rs b/src/ioctl/patterns.rs
@@ -29,7 +29,7 @@ impl<const OPCODE: Opcode> NoArg<OPCODE> {
     ///
     /// - `OPCODE` must provide a valid opcode.
     #[inline]
-    pub unsafe fn new() -> Self {
+    pub const unsafe fn new() -> Self {
         Self {}
     }
 }
@@ -81,7 +81,7 @@ impl<const OPCODE: Opcode, Output> Getter<OPCODE, Output> {
     /// - For this opcode, `Output` must be the type that the kernel expects to
     ///   write into.
     #[inline]
-    pub unsafe fn new() -> Self {
+    pub const unsafe fn new() -> Self {
         Self {
             output: mem::MaybeUninit::uninit(),
         }
@@ -138,7 +138,7 @@ impl<const OPCODE: Opcode, Input> Setter<OPCODE, Input> {
     /// - For this opcode, `Input` must be the type that the kernel expects to
     ///   get.
     #[inline]
-    pub unsafe fn new(input: Input) -> Self {
+    pub const unsafe fn new(input: Input) -> Self {
         Self { input }
     }
 }
@@ -229,7 +229,7 @@ impl<const OPCODE: Opcode> IntegerSetter<OPCODE> {
     /// - For this opcode, it must expect an integer.
     /// - The integer is in the valid range for this opcode.
     #[inline]
-    pub unsafe fn new_usize(value: usize) -> Self {
+    pub const unsafe fn new_usize(value: usize) -> Self {
         Self { value: value as _ }
     }
 
@@ -241,7 +241,7 @@ impl<const OPCODE: Opcode> IntegerSetter<OPCODE> {
     /// - For this opcode, it must expect an integer.
     /// - The integer is in the valid range for this opcode.
     #[inline]
-    pub unsafe fn new_pointer(value: &mut c::c_void) -> Self {
+    pub const unsafe fn new_pointer(value: *mut c::c_void) -> Self {
         Self { value }
     }
 }
diff --git a/src/net/socket_addr_any.rs b/src/net/socket_addr_any.rs
@@ -26,7 +26,7 @@ pub(crate) struct SocketAddrBuf {
 
 impl SocketAddrBuf {
     #[inline]
-    pub(crate) fn new() -> Self {
+    pub(crate) const fn new() -> Self {
         Self {
             len: size_of::<SocketAddrStorage>() as c::socklen_t,
             storage: MaybeUninit::<SocketAddrStorage>::uninit(),
@@ -97,7 +97,7 @@ impl SocketAddrAny {
     /// * `storage` must contain a valid socket address.
     /// * `len` bytes must be initialized.
     #[inline]
-    pub unsafe fn new(storage: MaybeUninit<SocketAddrStorage>, len: SocketAddrLen) -> Self {
+    pub const unsafe fn new(storage: MaybeUninit<SocketAddrStorage>, len: SocketAddrLen) -> Self {
         assert!(len as usize >= size_of::<read_sockaddr::sockaddr_header>());
         assert!(len as usize <= size_of::<SocketAddrStorage>());
         let len = NonZeroU32::new_unchecked(len);
diff --git a/src/net/types.rs b/src/net/types.rs
@@ -1130,13 +1130,13 @@ pub mod netlink {
     impl SocketAddrNetlink {
         /// Construct a netlink address
         #[inline]
-        pub fn new(pid: u32, groups: u32) -> Self {
+        pub const fn new(pid: u32, groups: u32) -> Self {
             Self { pid, groups }
         }
 
         /// Return port id.
         #[inline]
-        pub fn pid(&self) -> u32 {
+        pub const fn pid(&self) -> u32 {
             self.pid
         }
 
@@ -1148,7 +1148,7 @@ pub mod netlink {
 
         /// Return multicast groups mask.
         #[inline]
-        pub fn groups(&self) -> u32 {
+        pub const fn groups(&self) -> u32 {
             self.groups
         }
 
@@ -1702,7 +1702,7 @@ pub mod xdp {
     impl SocketAddrXdp {
         /// Construct a new XDP address.
         #[inline]
-        pub fn new(flags: SocketAddrXdpFlags, interface_index: u32, queue_id: u32) -> Self {
+        pub const fn new(flags: SocketAddrXdpFlags, interface_index: u32, queue_id: u32) -> Self {
             Self {
                 sxdp_flags: flags,
                 sxdp_ifindex: interface_index,
diff --git a/src/path/dec_int.rs b/src/path/dec_int.rs
@@ -164,13 +164,14 @@ impl DecInt {
         let mut buf = [MaybeUninit::uninit(); BUF_LEN];
         buf[BUF_LEN - 1] = MaybeUninit::new(b'\0');
 
-        // We use `loop { …; if cond { break } }` instead of `while !cond { … }` so the
-        // loop is entered at least once. This way `0` does not need a special
-        // handling.
+        // We use `loop { …; if cond { break } }` instead of
+        // `while !cond { … }` so the loop is entered at least once. This way
+        // `0` does not need a special handling.
         loop {
             len += 1;
             if len > BUF_LEN {
-                // SAFETY: a stringified i64/u64 cannot be longer than `U64_MAX_STR_LEN` bytes
+                // SAFETY: A stringified i64/u64 cannot be longer than
+                // `U64_MAX_STR_LEN` bytes.
                 unsafe { unreachable_unchecked() };
             }
             buf[BUF_LEN - len] = MaybeUninit::new(b'0' + i.div_mod_10());
@@ -182,7 +183,8 @@ impl DecInt {
         if is_neg {
             len += 1;
             if len > BUF_LEN {
-                // SAFETY: a stringified i64/u64 cannot be longer than `U64_MAX_STR_LEN` bytes
+                // SAFETY: A stringified i64/u64 cannot be longer than
+                // `U64_MAX_STR_LEN` bytes.
                 unsafe { unreachable_unchecked() };
             }
             buf[BUF_LEN - len] = MaybeUninit::new(b'-');
@@ -224,7 +226,8 @@ impl DecInt {
     pub fn as_bytes_with_nul(&self) -> &[u8] {
         let len = NonZeroUsize::from(self.len).get();
         if len > BUF_LEN {
-            // SAFETY: a stringified i64/u64 cannot be longer than `U64_MAX_STR_LEN` bytes
+            // SAFETY: A stringified i64/u64 cannot be longer than
+            // `U64_MAX_STR_LEN` bytes.
             unsafe { unreachable_unchecked() };
         }
         let init = &self.buf[(self.buf.len() - len)..];
diff --git a/src/pid.rs b/src/pid.rs
@@ -73,8 +73,11 @@ impl Pid {
 
     /// Converts an `Option<Pid>` into a `RawPid`.
     #[inline]
-    pub fn as_raw(pid: Option<Self>) -> RawPid {
-        pid.map_or(0, |pid| pid.0.get())
+    pub const fn as_raw(pid: Option<Self>) -> RawPid {
+        match pid {
+            Some(pid) => pid.0.get(),
+            None => 0,
+        }
     }
 
     /// Test whether this pid represents the init process (pid 1).
diff --git a/src/weak.rs b/src/weak.rs
@@ -74,13 +74,14 @@ impl<F> Weak<F> {
                 NULL => None,
                 addr => {
                     let func = mem::transmute_copy::<*mut c_void, F>(&addr);
-                    // The caller is presumably going to read through this value
-                    // (by calling the function we've dlsymed). This means we'd
-                    // need to have loaded it with at least C11's consume
-                    // ordering in order to be guaranteed that the data we read
-                    // from the pointer isn't from before the pointer was
-                    // stored. Rust has no equivalent to memory_order_consume,
-                    // so we use an acquire fence (sorry, ARM).
+                    // The caller is presumably going to read through this
+                    // value (by calling the function we've dlsymed). This
+                    // means we'd need to have loaded it with at least C11's
+                    // consume ordering in order to be guaranteed that the data
+                    // we read from the pointer isn't from before the pointer
+                    // was stored. Rust has no equivalent to
+                    // memory_order_consume, so we use an acquire fence (sorry,
+                    // ARM).
                     //
                     // Now, in practice this likely isn't needed even on CPUs
                     // where relaxed and consume mean different things. The
diff --git a/tests/io_uring/main.rs b/tests/io_uring/main.rs
@@ -1,4 +1,7 @@
+//! Tests for [`rustix::io_uring`].
+
+#![cfg(feature = "io_uring")]
+
 #[cfg(linux_kernel)]
-#[cfg(feature = "io_uring")]
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 mod register;
diff --git a/tests/process/fcntl_getlk.rs b/tests/process/fcntl_getlk.rs
@@ -6,7 +6,6 @@ use std::fs::File;
 use std::os::unix::process::CommandExt as _;
 use std::process::Command;
 
-#[cfg(feature = "fs")]
 #[test]
 #[serial]
 fn test_fcntl_getlk() {

Original file line number	Diff line number	Diff line change
`@@ -20,8 +20,8 @@`
`20`	`20`	`))]`
`21`	`21`	`fn main() {`
`22`	`22`	`unimplemented!(`
`23`		`- "Add --cfg=criterion to RUSTFLAGS and enable the \"fs\", \"time\", \"process\", and \"stdio\" cargo \`
`24`		`- features."`
	`23`	`+ "Add --cfg=criterion to RUSTFLAGS and enable the \"fs\", \"time\", \"process\", and \`
	`24`	`+ \"stdio\" cargo features."`
`25`	`25`	`)`
`26`	`26`	`}`
`27`	`27`
Original file line number	Diff line number	Diff line change
`@@ -154,7 +154,8 @@ impl Dir {`
`154`	`154`
`155`	`155`	/// `readdir(self)`, where `None` means the end of the directory.
`156`	`156`	`pub fn read(&mut self) -> Option<io::Result<DirEntry>> {`
`157`		`- // If we've seen errors, don't continue to try to read anything further.`
	`157`	`+ // If we've seen errors, don't continue to try to read anything`
	`158`	`+ // further.`
`158`	`159`	`if self.any_errors {`
`159`	`160`	`return None;`
`160`	`161`	`}`
Original file line number	Diff line number	Diff line change
`@@ -110,7 +110,8 @@ impl Dir {`
`110`	`110`
`111`	`111`	/// `readdir(self)`, where `None` means the end of the directory.
`112`	`112`	`pub fn read(&mut self) -> Option<io::Result<DirEntry>> {`
`113`		`- // If we've seen errors, don't continue to try to read anything further.`
	`113`	`+ // If we've seen errors, don't continue to try to read anything`
	`114`	`+ // further.`
`114`	`115`	`if self.any_errors {`
`115`	`116`	`return None;`
`116`	`117`	`}`
Original file line number	Diff line number	Diff line change
`@@ -548,7 +548,8 @@ pub(crate) fn fcntl_getlk(fd: BorrowedFd<'_>, lock: &Flock) -> io::Result<Option`
`548`	`548`	`))?`
`549`	`549`	`}`
`550`	`550`
`551`		- // If no blocking lock is found, `fcntl(GETLK, ..)` sets `l_type` to `F_UNLCK`
	`551`	+ // If no blocking lock is found, `fcntl(GETLK, ..)` sets `l_type` to
	`552`	+ // `F_UNLCK`.
`552`	`553`	`if curr_lock.l_type == c::F_UNLCK as _ {`
`553`	`554`	`Ok(None)`
`554`	`555`	`} else {`