Miscellaneous documentation and debug output fixes. (#1390)

Author: sunfishcode

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();

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)
     }

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);
     }

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;

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]

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;

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()

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 {

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

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)]

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)
+        );
     }
 }

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

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)]