Miscellaneous documentation and debug output fixes. (#1390)

sunfishcode · web-flow · commit f26edabb6dbb · 2025-03-06T10:10:49.000-08:00
diff --git a/examples/buffer_errors.rs b/examples/buffer_errors.rs
@@ -70,7 +70,7 @@ fn error_retry_closure_uninit() {
 
     let mut event_buf = [MaybeUninit::<u8>::uninit(); 4];
 
-    // Ideally we'd write this, but it gets:
+    // It's tempting to write this, but it gets:
     // "captured variable cannot escape `FnMut` closure body".
     /*
     rustix::io::retry_on_intr(|| b(&mut event_buf)).unwrap();
diff --git a/examples/stdio.rs b/examples/stdio.rs
@@ -348,6 +348,8 @@ fn key(b: u8) -> String {
         format!("^{}", (b + 0x40) as char)
     } else if b == 0x7f {
         "^?".to_string()
+    } else if b >= 0x80 {
+        format!("M-{}", key(b - 0x80))
     } else {
         format!("{}", b as char)
     }
diff --git a/src/backend/libc/event/syscalls.rs b/src/backend/libc/event/syscalls.rs
@@ -421,7 +421,7 @@ pub(crate) unsafe fn port_getn(
     };
 
     // `port_getn` special-cases a max value of 0 to be a query that returns
-    // the number of events, so so bail out early if needed.
+    // the number of events, so bail out early if needed.
     if events.1 == 0 {
         return Ok(0);
     }
diff --git a/src/backend/libc/mount/types.rs b/src/backend/libc/mount/types.rs
@@ -312,8 +312,8 @@ bitflags! {
         /// Mount and unmount events propagate from the upstream peer group
         /// into the downstream.
         ///
-        /// In Linux documentation, this flag is named <code>MS_SLAVE</code>,
-        /// and the concepts of “upstream” and “downstream” are called
+        /// In Linux documentation, this flag is named `MS_SLAVE`, and the
+        /// concepts of “upstream” and “downstream” are called
         /// “master” and “slave”.
         #[doc(alias = "SLAVE")]
         const DOWNSTREAM = c::MS_SLAVE;
diff --git a/src/backend/libc/net/netdevice.rs b/src/backend/libc/net/netdevice.rs
@@ -6,13 +6,13 @@
 use crate::alloc::string::String;
 use crate::backend::c;
 use crate::backend::io::syscalls::ioctl;
-use crate::fd::AsFd;
+use crate::fd::BorrowedFd;
 use crate::io;
 #[cfg(feature = "alloc")]
 use c::SIOCGIFNAME;
 use c::{__c_anonymous_ifr_ifru, c_char, ifreq, IFNAMSIZ, SIOCGIFINDEX};
 
-pub(crate) fn name_to_index(fd: impl AsFd, if_name: &str) -> io::Result<u32> {
+pub(crate) fn name_to_index(fd: BorrowedFd<'_>, if_name: &str) -> io::Result<u32> {
     let if_name_bytes = if_name.as_bytes();
     if if_name_bytes.len() >= IFNAMSIZ as usize {
         return Err(io::Errno::NODEV);
@@ -26,21 +26,21 @@ pub(crate) fn name_to_index(fd: impl AsFd, if_name: &str) -> io::Result<u32> {
     let mut if_name_c_char_iter = if_name_bytes.iter().map(|byte| *byte as c_char);
     ifreq.ifr_name[..if_name_bytes.len()].fill_with(|| if_name_c_char_iter.next().unwrap());
 
-    unsafe { ioctl(fd.as_fd(), SIOCGIFINDEX as _, &mut ifreq as *mut ifreq as _) }?;
+    unsafe { ioctl(fd, SIOCGIFINDEX as _, &mut ifreq as *mut ifreq as _) }?;
     let index = unsafe { ifreq.ifr_ifru.ifru_ifindex };
     Ok(index as u32)
 }
 
 #[cfg(feature = "alloc")]
-pub(crate) fn index_to_name(fd: impl AsFd, index: u32) -> io::Result<String> {
+pub(crate) fn index_to_name(fd: BorrowedFd<'_>, index: u32) -> io::Result<String> {
     let mut ifreq = ifreq {
         ifr_name: [0; 16],
         ifr_ifru: __c_anonymous_ifr_ifru {
             ifru_ifindex: index as _,
         },
     };
 
-    unsafe { ioctl(fd.as_fd(), SIOCGIFNAME as _, &mut ifreq as *mut ifreq as _) }?;
+    unsafe { ioctl(fd, SIOCGIFNAME as _, &mut ifreq as *mut ifreq as _) }?;
 
     if let Some(nul_byte) = ifreq.ifr_name.iter().position(|char| *char == 0) {
         let name: String = ifreq.ifr_name[..nul_byte]
diff --git a/src/backend/linux_raw/mount/types.rs b/src/backend/linux_raw/mount/types.rs
@@ -304,8 +304,8 @@ bitflags! {
         /// Mount and unmount events propagate from the upstream peer group
         /// into the downstream.
         ///
-        /// In Linux documentation, this flag is named <code>MS_SLAVE</code>,
-        /// and the concepts of “upstream” and “downstream” are called
+        /// In Linux documentation, this flag is named `MS_SLAVE`, and the
+        /// concepts of “upstream” and “downstream” are called
         /// “master” and “slave”.
         #[doc(alias = "SLAVE")]
         const DOWNSTREAM = linux_raw_sys::general::MS_SLAVE;
diff --git a/src/backend/linux_raw/net/netdevice.rs b/src/backend/linux_raw/net/netdevice.rs
@@ -3,7 +3,7 @@
 #![allow(unsafe_code)]
 
 use crate::backend::io::syscalls::ioctl;
-use crate::fd::AsFd;
+use crate::fd::BorrowedFd;
 use crate::io;
 use core::ptr::addr_of_mut;
 use core::{slice, str};
@@ -15,7 +15,7 @@ use linux_raw_sys::net::{ifreq, ifreq__bindgen_ty_1, ifreq__bindgen_ty_2, IFNAMS
 #[cfg(feature = "alloc")]
 use {alloc::borrow::ToOwned, alloc::string::String};
 
-pub(crate) fn name_to_index(fd: impl AsFd, if_name: &str) -> io::Result<u32> {
+pub(crate) fn name_to_index(fd: BorrowedFd<'_>, if_name: &str) -> io::Result<u32> {
     let if_name_bytes = if_name.as_bytes();
     if if_name_bytes.len() >= IFNAMSIZ as usize {
         return Err(io::Errno::NODEV);
@@ -35,21 +35,21 @@ pub(crate) fn name_to_index(fd: impl AsFd, if_name: &str) -> io::Result<u32> {
     };
     unsafe { ifreq.ifr_ifrn.ifrn_name[..if_name_bytes.len()].copy_from_slice(if_name_bytes) };
 
-    unsafe { ioctl(fd.as_fd(), SIOCGIFINDEX, addr_of_mut!(ifreq).cast()) }?;
+    unsafe { ioctl(fd, SIOCGIFINDEX, addr_of_mut!(ifreq).cast()) }?;
     let index = unsafe { ifreq.ifr_ifru.ifru_ivalue };
     Ok(index as u32)
 }
 
 #[cfg(feature = "alloc")]
-pub(crate) fn index_to_name(fd: impl AsFd, index: u32) -> io::Result<String> {
+pub(crate) fn index_to_name(fd: BorrowedFd<'_>, index: u32) -> io::Result<String> {
     let mut ifreq = ifreq {
         ifr_ifrn: ifreq__bindgen_ty_1 { ifrn_name: [0; 16] },
         ifr_ifru: ifreq__bindgen_ty_2 {
             ifru_ivalue: index as _,
         },
     };
 
-    unsafe { ioctl(fd.as_fd(), SIOCGIFNAME, addr_of_mut!(ifreq).cast()) }?;
+    unsafe { ioctl(fd, SIOCGIFNAME, addr_of_mut!(ifreq).cast()) }?;
 
     if let Some(nul_byte) = unsafe { ifreq.ifr_ifrn.ifrn_name }
         .iter()
diff --git a/src/backend/linux_raw/param/auxv.rs b/src/backend/linux_raw/param/auxv.rs
@@ -487,10 +487,7 @@ unsafe fn check_elf_base(base: *const Elf_Ehdr) -> Option<NonNull<Elf_Ehdr>> {
         return None;
     }
 
-    let hdr = match check_raw_pointer::<Elf_Ehdr>(base as *mut _) {
-        Some(hdr) => hdr,
-        None => return None,
-    };
+    let hdr = check_raw_pointer::<Elf_Ehdr>(base as *mut _)?;
 
     let hdr = hdr.as_ref();
     if hdr.e_ident[..SELFMAG] != ELFMAG {
diff --git a/src/io/close.rs b/src/io/close.rs
@@ -10,7 +10,7 @@ use backend::fd::RawFd;
 
 /// `close(raw_fd)`—Closes a `RawFd` directly.
 ///
-/// Most users won't need to use this, as `OwnedFd` automatically closes its
+/// Most users won't need to use this, as [`OwnedFd`] automatically closes its
 /// file descriptor on `Drop`.
 ///
 /// This function does not return a `Result`, as it is the [responsibility] of
@@ -33,6 +33,7 @@ use backend::fd::RawFd;
 ///  - [illumos]
 ///  - [glibc]
 ///
+/// [`OwnedFd`]: crate::fd::OwnedFd
 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#close-and-shutdownget-outta-my-face
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/close.html
 /// [Linux]: https://man7.org/linux/man-pages/man2/close.2.html
diff --git a/src/lib.rs b/src/lib.rs
@@ -89,13 +89,12 @@
 //! [`cap-std`]: https://crates.io/crates/cap-std
 //! [`system-interface`]: https://crates.io/crates/system-interface
 //! [`io-streams`]: https://crates.io/crates/io-streams
-//! [`getrandom`]: https://crates.io/crates/getrandom
-//! [`bitflags`]: https://crates.io/crates/bitflags
-//! [`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html
-//! [`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html
+//! [`bitflags`]: bitflags
+//! [`AsFd`]: crate::fd::AsFd
+//! [`OwnedFd`]: crate::fd::OwnedFd
 //! [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
 //! [`Arg`]: path::Arg
-//! [support for externally defined flags]: https://docs.rs/bitflags/*/bitflags/#externally-defined-flags
+//! [support for externally defined flags]: bitflags#externally-defined-flags
 
 #![deny(missing_docs)]
 #![allow(stable_features)]
diff --git a/src/net/netdevice.rs b/src/net/netdevice.rs
@@ -34,7 +34,7 @@ use alloc::string::String;
 #[inline]
 #[doc(alias = "SIOCGIFINDEX")]
 pub fn name_to_index<Fd: AsFd>(fd: Fd, if_name: &str) -> io::Result<u32> {
-    crate::backend::net::netdevice::name_to_index(fd, if_name)
+    crate::backend::net::netdevice::name_to_index(fd.as_fd(), if_name)
 }
 
 /// `ioctl(fd, SIOCGIFNAME, ifreq)`—Returns the interface name for a given
@@ -52,12 +52,13 @@ pub fn name_to_index<Fd: AsFd>(fd: Fd, if_name: &str) -> io::Result<u32> {
 #[cfg(feature = "alloc")]
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub fn index_to_name<Fd: AsFd>(fd: Fd, index: u32) -> io::Result<String> {
-    crate::backend::net::netdevice::index_to_name(fd, index)
+    crate::backend::net::netdevice::index_to_name(fd.as_fd(), index)
 }
 
 #[cfg(test)]
 mod tests {
     use crate::backend::net::netdevice::{index_to_name, name_to_index};
+    use crate::fd::AsFd;
     use crate::net::{AddressFamily, SocketFlags, SocketType};
 
     #[test]
@@ -77,7 +78,7 @@ mod tests {
             .0
             .parse::<u32>()
             .unwrap();
-        assert_eq!(Ok(loopback_index), name_to_index(fd, "lo"));
+        assert_eq!(Ok(loopback_index), name_to_index(fd.as_fd(), "lo"));
     }
 
     #[test]
@@ -98,6 +99,9 @@ mod tests {
             .0
             .parse::<u32>()
             .unwrap();
-        assert_eq!(Ok("lo".to_owned()), index_to_name(fd, loopback_index));
+        assert_eq!(
+            Ok("lo".to_owned()),
+            index_to_name(fd.as_fd(), loopback_index)
+        );
     }
 }
diff --git a/src/net/send_recv/msg.rs b/src/net/send_recv/msg.rs
@@ -703,7 +703,7 @@ pub fn sendmsg<Fd: AsFd>(
 ///  - [DragonFly BSD]
 ///  - [illumos]
 ///
-/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html
+/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/sendmsg.html
 /// [Linux]: https://man7.org/linux/man-pages/man2/sendmsg.2.html
 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/sendmsg.2.html
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=sendmsg&sektion=2
diff --git a/src/process/wait.rs b/src/process/wait.rs
@@ -72,7 +72,7 @@ bitflags! {
 }
 
 /// The status of a child process after calling [`wait`]/[`waitpid`].
-#[derive(Debug, Clone, Copy)]
+#[derive(Clone, Copy)]
 #[repr(transparent)]
 pub struct WaitStatus(i32);
 
@@ -91,31 +91,36 @@ impl WaitStatus {
 
     /// Returns whether the process is currently stopped.
     #[inline]
+    #[doc(alias = "WIFSTOPPED")]
     pub fn stopped(self) -> bool {
         backend::process::wait::WIFSTOPPED(self.0)
     }
 
     /// Returns whether the process has exited normally.
     #[inline]
+    #[doc(alias = "WIFEXITED")]
     pub fn exited(self) -> bool {
         backend::process::wait::WIFEXITED(self.0)
     }
 
     /// Returns whether the process was terminated by a signal.
     #[inline]
+    #[doc(alias = "WIFSIGNALED")]
     pub fn signaled(self) -> bool {
         backend::process::wait::WIFSIGNALED(self.0)
     }
 
     /// Returns whether the process has continued from a job control stop.
     #[inline]
+    #[doc(alias = "WIFCONTINUED")]
     pub fn continued(self) -> bool {
         backend::process::wait::WIFCONTINUED(self.0)
     }
 
     /// Returns the number of the signal that stopped the process, if the
     /// process was stopped by a signal.
     #[inline]
+    #[doc(alias = "WSTOPSIG")]
     pub fn stopping_signal(self) -> Option<i32> {
         if self.stopped() {
             Some(backend::process::wait::WSTOPSIG(self.0))
@@ -127,6 +132,7 @@ impl WaitStatus {
     /// Returns the exit status number returned by the process, if it exited
     /// normally.
     #[inline]
+    #[doc(alias = "WEXITSTATUS")]
     pub fn exit_status(self) -> Option<i32> {
         if self.exited() {
             Some(backend::process::wait::WEXITSTATUS(self.0))
@@ -138,6 +144,7 @@ impl WaitStatus {
     /// Returns the number of the signal that terminated the process, if the
     /// process was terminated by a signal.
     #[inline]
+    #[doc(alias = "WTERMSIG")]
     pub fn terminating_signal(self) -> Option<i32> {
         if self.signaled() {
             Some(backend::process::wait::WTERMSIG(self.0))
@@ -147,6 +154,26 @@ impl WaitStatus {
     }
 }
 
+impl fmt::Debug for WaitStatus {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let mut s = f.debug_struct("WaitStatus");
+        s.field("stopped", &self.stopped());
+        s.field("exited", &self.exited());
+        s.field("signaled", &self.signaled());
+        s.field("continued", &self.continued());
+        if let Some(stopping_signal) = self.stopping_signal() {
+            s.field("stopping_signal", &stopping_signal);
+        }
+        if let Some(exit_status) = self.exit_status() {
+            s.field("exit_status", &exit_status);
+        }
+        if let Some(terminating_signal) = self.terminating_signal() {
+            s.field("terminating_signal", &terminating_signal);
+        }
+        s.finish()
+    }
+}
+
 /// The status of a process after calling [`waitid`].
 #[derive(Clone, Copy)]
 #[repr(transparent)]
diff --git a/src/termios/types.rs b/src/termios/types.rs

Original file line number	Diff line number	Diff line change
`@@ -348,6 +348,8 @@ fn key(b: u8) -> String {`
`348`	`348`	`format!("^{}", (b + 0x40) as char)`
`349`	`349`	`} else if b == 0x7f {`
`350`	`350`	`"^?".to_string()`
	`351`	`+ } else if b >= 0x80 {`
	`352`	`+ format!("M-{}", key(b - 0x80))`
`351`	`353`	`} else {`
`352`	`354`	`format!("{}", b as char)`
`353`	`355`	`}`
Original file line number	Diff line number	Diff line change
`@@ -421,7 +421,7 @@ pub(crate) unsafe fn port_getn(`
`421`	`421`	`};`
`422`	`422`
`423`	`423`	// `port_getn` special-cases a max value of 0 to be a query that returns
`424`		`- // the number of events, so so bail out early if needed.`
	`424`	`+ // the number of events, so bail out early if needed.`
`425`	`425`	`if events.1 == 0 {`
`426`	`426`	`return Ok(0);`
`427`	`427`	`}`