refactor: a new TimestampSpec type for the time args of utimensat and futimens

Author: SteveLauC

CHANGELOG.md

@@ -19,6 +19,9 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - With I/O-safe type applied in `pty::OpenptyResult` and `pty::ForkptyResult`,
   users no longer need to manually close the file descriptors in these types.
   ([#1921](https://github.com/nix-rust/nix/pull/1921))
+- A new type `TimestampSpec` for the time arguments of `utimensat(2)` and
+  `futimens(2)` to make use of `UTIME_OMIT` and `UTIME_NOW`.
+  ([#1879](https://github.com/nix-rust/nix/pull/1879))
 
 ### Fixed
 ### Removed

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,67 @@ 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),
+}
+
+/// Construct a new [`libc::timespec`] instance according to the value of [`TimestampSpec`].
+///
+/// This is used in the implementations of [`futimens`] and [`utimensat`]. As an
+/// end user, you may NOT find this trait implementation useful.
+#[cfg(not(target_os = "redox"))] // Redox does not support `UTIME_OMIT` and `UTIME_NOW`
+impl From<&TimestampSpec> for libc::timespec {
+    fn from(spec: &TimestampSpec) -> Self {
+        let mut default_value = super::time::zero_init_timespec();
+
+        match spec {
+            TimestampSpec::Omit => default_value.tv_nsec = libc::UTIME_OMIT as _,
+            TimestampSpec::Now => default_value.tv_nsec = libc::UTIME_NOW as _,
+            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 = [atime.into(), mtime.into()];
+    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 +494,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 = [atime.into(), mtime.into()];
     let res = path.with_nix_path(|cstr| unsafe {
         libc::utimensat(
             at_rawfd(dirfd),

src/sys/time.rs

@@ -6,7 +6,7 @@ use std::convert::From;
 use std::time::Duration;
 use std::{cmp, fmt, ops};
 
-const fn zero_init_timespec() -> timespec {
+pub(crate) const fn zero_init_timespec() -> timespec {
     // `std::mem::MaybeUninit::zeroed()` is not yet a const fn
     // (https://github.com/rust-lang/rust/issues/91850) so we will instead initialize an array of
     // the appropriate size to zero and then transmute it to a timespec value.

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