refactor: I/O safety for unistd.rs (nix-rust#2440)

* refactor: I/O safety for sys/unistd.rs

* chore: changelog entry

* remove link to dup3_raw() since it is not available on all OSes

* fix: imports

* fix test

* fix test on FreeBSD & update docs

changelog/2440.changed.md

@@ -0,0 +1 @@
+Module unistd now adopts I/O safety.

src/fcntl.rs

@@ -13,8 +13,6 @@ use std::ffi::CStr;
 use std::ffi::OsString;
 #[cfg(not(any(target_os = "redox", target_os = "solaris")))]
 use std::ops::{Deref, DerefMut};
-#[cfg(not(target_os = "redox"))]
-use std::os::raw;
 use std::os::unix::ffi::OsStringExt;
 #[cfg(not(any(target_os = "redox", target_os = "solaris")))]
 use std::os::unix::io::OwnedFd;
@@ -234,12 +232,8 @@ libc_bitflags!(
 );
 
 /// Computes the raw fd consumed by a function of the form `*at`.
-#[cfg(any(
-    all(feature = "fs", not(target_os = "redox")),
-    all(feature = "process", linux_android),
-    all(feature = "fanotify", target_os = "linux")
-))]
-pub(crate) fn at_rawfd(fd: Option<RawFd>) -> raw::c_int {
+#[cfg(all(feature = "fanotify", target_os = "linux"))]
+pub(crate) fn at_rawfd(fd: Option<RawFd>) -> RawFd {
     fd.unwrap_or(libc::AT_FDCWD)
 }
 

src/poll.rs

@@ -36,7 +36,7 @@ impl<'fd> PollFd<'fd> {
     /// let mut fds = [pfd];
     /// poll(&mut fds, PollTimeout::NONE).unwrap();
     /// let mut buf = [0u8; 80];
-    /// read(r.as_raw_fd(), &mut buf[..]);
+    /// read(&r, &mut buf[..]);
     /// ```
     // Unlike I/O functions, constructors like this must take `BorrowedFd`
     // instead of AsFd or &AsFd.  Otherwise, an `OwnedFd` argument would be

src/pty.rs

@@ -73,7 +73,7 @@ impl IntoRawFd for PtyMaster {
 
 impl io::Read for PtyMaster {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
-        unistd::read(self.0.as_raw_fd(), buf).map_err(io::Error::from)
+        unistd::read(&self.0, buf).map_err(io::Error::from)
     }
 }
 
@@ -88,7 +88,7 @@ impl io::Write for PtyMaster {
 
 impl io::Read for &PtyMaster {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
-        unistd::read(self.0.as_raw_fd(), buf).map_err(io::Error::from)
+        unistd::read(&self.0, buf).map_err(io::Error::from)
     }
 }
 

src/sys/eventfd.rs

@@ -1,6 +1,6 @@
 use crate::errno::Errno;
-use crate::{Result,unistd};
-use std::os::unix::io::{FromRawFd, OwnedFd, AsRawFd, AsFd, RawFd, BorrowedFd};
+use crate::{unistd, Result};
+use std::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, OwnedFd, RawFd};
 
 libc_bitflags! {
     pub struct EfdFlags: libc::c_int {
@@ -10,7 +10,10 @@ libc_bitflags! {
     }
 }
 
-#[deprecated(since = "0.28.0", note = "Use EventFd::from_value_and_flags() instead")]
+#[deprecated(
+    since = "0.28.0",
+    note = "Use EventFd::from_value_and_flags() instead"
+)]
 pub fn eventfd(initval: libc::c_uint, flags: EfdFlags) -> Result<OwnedFd> {
     let res = unsafe { libc::eventfd(initval, flags.bits()) };
 
@@ -26,9 +29,12 @@ impl EventFd {
         Self::from_value_and_flags(0, EfdFlags::empty())
     }
     /// Constructs [`EventFd`] with the given `init_val` and `flags`.
-    /// 
+    ///
     /// Wrapper around [`libc::eventfd`].
-    pub fn from_value_and_flags(init_val: u32, flags: EfdFlags) -> Result<Self> {
+    pub fn from_value_and_flags(
+        init_val: u32,
+        flags: EfdFlags,
+    ) -> Result<Self> {
         let res = unsafe { libc::eventfd(init_val, flags.bits()) };
         Errno::result(res).map(|r| Self(unsafe { OwnedFd::from_raw_fd(r) }))
     }
@@ -41,29 +47,29 @@ impl EventFd {
         Self::from_value_and_flags(init_val, EfdFlags::empty())
     }
     /// Arms `self`, a following call to `poll`, `select` or `epoll` will return immediately.
-    /// 
+    ///
     /// [`EventFd::write`] with `1`.
     pub fn arm(&self) -> Result<usize> {
         self.write(1)
     }
     /// Defuses `self`, a following call to `poll`, `select` or `epoll` will block.
-    /// 
+    ///
     /// [`EventFd::write`] with `0`.
     pub fn defuse(&self) -> Result<usize> {
         self.write(0)
     }
     /// Enqueues `value` triggers.
-    /// 
+    ///
     /// The next `value` calls to `poll`, `select` or `epoll` will return immediately.
-    /// 
+    ///
     /// [`EventFd::write`] with `value`.
-    pub fn write(&self, value: u64) -> Result<usize> { 
-        unistd::write(&self.0,&value.to_ne_bytes())
+    pub fn write(&self, value: u64) -> Result<usize> {
+        unistd::write(&self.0, &value.to_ne_bytes())
     }
     // Reads the value from the file descriptor.
     pub fn read(&self) -> Result<u64> {
         let mut arr = [0; std::mem::size_of::<u64>()];
-        unistd::read(self.0.as_raw_fd(),&mut arr)?;
+        unistd::read(&self.0, &mut arr)?;
         Ok(u64::from_ne_bytes(arr))
     }
 }

src/sys/fanotify.rs

@@ -252,7 +252,11 @@ impl Drop for FanotifyEvent {
         if self.0.fd == libc::FAN_NOFD {
             return;
         }
-        let e = close(self.0.fd);
+        // SAFETY:
+        //
+        // If this fd is not `FAN_NOFD`, then it should be a valid, owned file
+        // descriptor, which means we can safely close it.
+        let e = unsafe { close(self.0.fd) };
         if !std::thread::panicking() && e == Err(Errno::EBADF) {
             panic!("Closing an invalid file descriptor!");
         };
@@ -362,7 +366,7 @@ impl Fanotify {
         let mut events = Vec::new();
         let mut offset = 0;
 
-        let nread = read(self.fd.as_raw_fd(), &mut buffer)?;
+        let nread = read(&self.fd, &mut buffer)?;
 
         while (nread - offset) >= metadata_size {
             let metadata = unsafe {

src/sys/inotify.rs

@@ -201,7 +201,7 @@ impl Inotify {
         let mut events = Vec::new();
         let mut offset = 0;
 
-        let nread = read(self.fd.as_raw_fd(), &mut buffer)?;
+        let nread = read(&self.fd, &mut buffer)?;
 
         while (nread - offset) >= header_size {
             let event = unsafe {

src/sys/timerfd.rs

@@ -208,7 +208,7 @@ impl TimerFd {
     ///
     /// Note: If the alarm is unset, then you will wait forever.
     pub fn wait(&self) -> Result<()> {
-        while let Err(e) = read(self.fd.as_fd().as_raw_fd(), &mut [0u8; 8]) {
+        while let Err(e) = read(&self.fd, &mut [0u8; 8]) {
             if e == Errno::ECANCELED {
                 break;
             }