refactor: use an enum to represent the timestamp update operation

Author: SteveLauC

README.md

@@ -17,7 +17,7 @@ usage.
 
 As an example of what Nix provides, examine the differences between what is
 exposed by libc and nix for the
-[gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html) system
+[gethostname](https://pubs.opengroup.org/onlinepubs/9699919799/functions/gethostname.html) system
 call:
 
 ```rust,ignore

src/sys/stat.rs

@@ -402,12 +402,87 @@ pub fn lutimes<P: ?Sized + NixPath>(
     Errno::result(res).map(drop)
 }
 
+/// Timestamp update operation specifier used in [`utimensat`] and [`futimens`].
+#[cfg(not(target_os = "redox"))] // Redox does not support `UTIME_OMIT` and `UTIME_NOW`
+#[derive(Copy, Clone, Debug)]
+pub enum TimestampSpec {
+    /// Leave the timestamp unchanged.
+    Omit,
+    /// Update the timestamp to `Now`
+    Now,
+    /// Update the timestamp to the specific value specified in `TimeSpec`.
+    Set(TimeSpec),
+}
+
+/// A helper function to construct an instance of `libc::timespec` according to
+/// the operation specified in `spec`.
+#[cfg(not(target_os = "redox"))] // Redox does not support `UTIME_OMIT` and `UTIME_NOW`
+fn create_timespec(spec: &TimestampSpec) -> libc::timespec {
+    let mut default_value = libc::timespec {
+        tv_sec: 0,
+        tv_nsec: 0,
+    };
+
+    match spec {
+        #[cfg(all(
+            target_os = "linux",
+            target_arch = "x86_64",
+            target_pointer_width = "32"
+        ))]
+        TimestampSpec::Omit => default_value.tv_nsec = libc::UTIME_OMIT as i64,
+        #[cfg(not(all(
+            target_os = "linux",
+            target_arch = "x86_64",
+            target_pointer_width = "32"
+        )))]
+        TimestampSpec::Omit => default_value.tv_nsec = libc::UTIME_OMIT,
+        #[cfg(all(
+            target_os = "linux",
+            target_arch = "x86_64",
+            target_pointer_width = "32"
+        ))]
+        TimestampSpec::Now => default_value.tv_nsec = libc::UTIME_NOW as i64,
+        #[cfg(not(all(
+            target_os = "linux",
+            target_arch = "x86_64",
+            target_pointer_width = "32"
+        )))]
+        TimestampSpec::Now => default_value.tv_nsec = libc::UTIME_NOW,
+        TimestampSpec::Set(time) => {
+            default_value.tv_sec = time.tv_sec();
+            default_value.tv_nsec = time.tv_nsec();
+        }
+    }
+
+    default_value
+}
+
+/// Change the access and modification times of the file specified by a file
+/// descriptor.
+///
+/// # References
+///
+/// [futimens(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/futimens.html).
+#[cfg(not(target_os = "redox"))] // Redox does not support `UTIME_OMIT` and `UTIME_NOW`
+#[inline]
+pub fn futimens(
+    fd: RawFd,
+    atime: TimestampSpec,
+    mtime: TimestampSpec,
+) -> Result<()> {
+    let times = [create_timespec(&atime), create_timespec(&mtime)];
+    let res = unsafe { libc::futimens(fd, &times[0]) };
+
+    Errno::result(res).map(drop)
+}
+
 /// Change the access and modification times of the file specified by a file descriptor.
 ///
 /// # References
 ///
 /// [futimens(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/futimens.html).
 #[inline]
+#[cfg(target_os = "redox")]
 pub fn futimens(fd: RawFd, atime: &TimeSpec, mtime: &TimeSpec) -> Result<()> {
     let times: [libc::timespec; 2] = [*atime.as_ref(), *mtime.as_ref()];
     let res = unsafe { libc::futimens(fd, &times[0]) };
@@ -439,20 +514,20 @@ pub enum UtimensatFlags {
 /// # References
 ///
 /// [utimensat(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/utimens.html).
-#[cfg(not(target_os = "redox"))]
+#[cfg(not(target_os = "redox"))] // Redox does not support `utimensat(2)` syscall
 #[cfg_attr(docsrs, doc(cfg(all())))]
 pub fn utimensat<P: ?Sized + NixPath>(
     dirfd: Option<RawFd>,
     path: &P,
-    atime: &TimeSpec,
-    mtime: &TimeSpec,
+    atime: TimestampSpec,
+    mtime: TimestampSpec,
     flag: UtimensatFlags,
 ) -> Result<()> {
     let atflag = match flag {
         UtimensatFlags::FollowSymlink => AtFlags::empty(),
         UtimensatFlags::NoFollowSymlink => AtFlags::AT_SYMLINK_NOFOLLOW,
     };
-    let times: [libc::timespec; 2] = [*atime.as_ref(), *mtime.as_ref()];
+    let times = [create_timespec(&atime), create_timespec(&mtime)];
     let res = path.with_nix_path(|cstr| unsafe {
         libc::utimensat(
             at_rawfd(dirfd),

test/test_stat.rs

@@ -32,15 +32,15 @@ use nix::sys::stat::utimensat;
 #[cfg(not(target_os = "redox"))]
 use nix::sys::stat::FchmodatFlags;
 use nix::sys::stat::Mode;
-#[cfg(not(any(target_os = "redox", target_os = "haiku")))]
-use nix::sys::stat::UtimensatFlags;
 #[cfg(not(target_os = "redox"))]
 use nix::sys::stat::{self};
 use nix::sys::stat::{fchmod, stat};
 #[cfg(not(target_os = "redox"))]
 use nix::sys::stat::{fchmodat, mkdirat};
 #[cfg(not(any(target_os = "redox", target_os = "haiku")))]
 use nix::sys::stat::{futimens, utimes};
+#[cfg(not(any(target_os = "redox", target_os = "haiku")))]
+use nix::sys::stat::{TimestampSpec, UtimensatFlags};
 
 #[cfg(not(any(target_os = "netbsd", target_os = "redox")))]
 use nix::sys::stat::FileStat;
@@ -275,10 +275,47 @@ fn test_futimens() {
     let fd = fcntl::open(&fullpath, fcntl::OFlag::empty(), stat::Mode::empty())
         .unwrap();
 
-    futimens(fd, &TimeSpec::seconds(10), &TimeSpec::seconds(20)).unwrap();
+    futimens(
+        fd,
+        TimestampSpec::Set(TimeSpec::seconds(10)),
+        TimestampSpec::Set(TimeSpec::seconds(20)),
+    )
+    .unwrap();
     assert_times_eq(10, 20, &fs::metadata(&fullpath).unwrap());
 }
 
+#[test]
+#[cfg(not(any(target_os = "redox", target_os = "haiku")))]
+fn test_futimens_unchanged() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let fullpath = tempdir.path().join("file");
+    drop(File::create(&fullpath).unwrap());
+    let fd = fcntl::open(&fullpath, fcntl::OFlag::empty(), stat::Mode::empty())
+        .unwrap();
+
+    let old_atime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .accessed()
+        .unwrap();
+    let old_mtime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .modified()
+        .unwrap();
+
+    futimens(fd, TimestampSpec::Omit, TimestampSpec::Omit).unwrap();
+
+    let new_atime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .accessed()
+        .unwrap();
+    let new_mtime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .modified()
+        .unwrap();
+    assert_eq!(old_atime, new_atime);
+    assert_eq!(old_mtime, new_mtime);
+}
+
 #[test]
 #[cfg(not(any(target_os = "redox", target_os = "haiku")))]
 fn test_utimensat() {
@@ -295,8 +332,8 @@ fn test_utimensat() {
     utimensat(
         Some(dirfd),
         filename,
-        &TimeSpec::seconds(12345),
-        &TimeSpec::seconds(678),
+        TimestampSpec::Set(TimeSpec::seconds(12345)),
+        TimestampSpec::Set(TimeSpec::seconds(678)),
         UtimensatFlags::FollowSymlink,
     )
     .unwrap();
@@ -307,14 +344,54 @@ fn test_utimensat() {
     utimensat(
         None,
         filename,
-        &TimeSpec::seconds(500),
-        &TimeSpec::seconds(800),
+        TimestampSpec::Set(TimeSpec::seconds(500)),
+        TimestampSpec::Set(TimeSpec::seconds(800)),
         UtimensatFlags::FollowSymlink,
     )
     .unwrap();
     assert_times_eq(500, 800, &fs::metadata(&fullpath).unwrap());
 }
 
+#[test]
+#[cfg(not(any(target_os = "redox", target_os = "haiku")))]
+fn test_utimensat_unchanged() {
+    let _dr = crate::DirRestore::new();
+    let tempdir = tempfile::tempdir().unwrap();
+    let filename = "foo.txt";
+    let fullpath = tempdir.path().join(filename);
+    drop(File::create(&fullpath).unwrap());
+    let dirfd =
+        fcntl::open(tempdir.path(), fcntl::OFlag::empty(), stat::Mode::empty())
+            .unwrap();
+
+    let old_atime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .accessed()
+        .unwrap();
+    let old_mtime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .modified()
+        .unwrap();
+    utimensat(
+        Some(dirfd),
+        filename,
+        TimestampSpec::Omit,
+        TimestampSpec::Omit,
+        UtimensatFlags::NoFollowSymlink,
+    )
+    .unwrap();
+    let new_atime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .accessed()
+        .unwrap();
+    let new_mtime = fs::metadata(fullpath.as_path())
+        .unwrap()
+        .modified()
+        .unwrap();
+    assert_eq!(old_atime, new_atime);
+    assert_eq!(old_mtime, new_mtime);
+}
+
 #[test]
 #[cfg(not(target_os = "redox"))]
 fn test_mkdirat_success_path() {