Add an Option To Preserve Parent Modification Time

Adds a `--parent-mtime`/`-m` option to restore the `mtime` of a
directory to the value prior to creating a clone.

Resolves #9

Author: hohle

.github/workflows/check.yaml

@@ -6,6 +6,9 @@ on:
   pull_request_target:
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   check:
     strategy:

Makefile

@@ -16,6 +16,7 @@ CFLAGS += \
     -Wno-unused-parameter \
     -Wno-gnu-conditional-omitted-operand \
     -Wno-macro-redefined \
+    -Wimplicit-fallthrough \
     -Wp,-D_FORTIFY_SOURCE=3 \
     -fexceptions \
     -fpic \
@@ -113,7 +114,7 @@ clean: clean-coverage
 
 report-coverage:
 	mkdir -p build/private/coverage
-	geninfo . -o build/private/coverage.info
+	geninfo . -o build/private/coverage.info --ignore-errors path
 	genhtml build/private/coverage.info -o build/private/coverage
 
 PREFIX ?= /usr/local

README.md

@@ -119,6 +119,12 @@ The following options are available:
 > from descending into directories that have a device number different than that
 > of the file from which the descent began.
 
+**-m**, **--parent-mtime**
+
+> Preserve the parent directory modification time (mtime) when a file is cloned.
+> Useful when working with backups or other programs that are sensitive to
+> directory changes.
+
 **-**?, **--help**
 
 > Print a summary of options and exit.

clone.c

@@ -1,4 +1,4 @@
-// Copyright © 2023 TTKB, LLC.
+// Copyright © 2023-2026 TTKB, LLC.
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are met:
@@ -36,6 +36,7 @@
 
 #include <err.h>
 #include <errno.h>
+#include <fcntl.h>
 #include <libgen.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -44,7 +45,7 @@
 
 #include "clone.h"
 
-int find_zero_file(const char* restrict path) {
+static int find_zero_file(const char* restrict path) {
     if (access(path, W_OK)) {
         return 1;
     }
@@ -97,7 +98,7 @@ char* tmp_name(const char* restrict path, char* restrict out, size_t size) {
     return out;
 }
 
-int genfile_clone(const char* src, const char* dst) {
+static int genfile_clone(const char* src, const char* dst) {
 #if defined(__APPLE__)
     return clonefile(src, dst, 0);
 #elif defined(__FREEBSD__)
@@ -129,26 +130,97 @@ int genfile_clone(const char* src, const char* dst) {
 #endif
 }
 
-int replace_with_clone(const char* src, const char* dst) {
+// get the parent directory mtime and return it and a file descriptor
+// for the directory. if return is 0, caller is responsible for closing
+// the returned fd
+static int dir_mtime(const char* path, int* fd_out, struct timespec* mtime_out) {
+    char buffer[PATH_MAX] = { 0 };
+    char* parent = dirname_r(path, buffer);
+    if (!parent) {
+        perror("dirname_r");
+        return -1;
+    }
+
+    int fd = open(parent, O_RDONLY);
+    if (fd == -1) {
+        perror("open parent dir");
+        return -1;
+    }
+
+    struct stat st;
+    if (fstat(fd, &st) == -1) {
+        perror("fstat parent dir");
+        close(fd);
+        return -1;
+    }
+
+    *fd_out = fd;
+    *mtime_out = st.st_mtimespec;
+    return 0;
+}
+
+// restore the provided mtime to the provided fd. fd is closed
+// before the function returns
+static void restore_dir_mtime(int fd, struct timespec mtime) {
+    struct timespec times[2] = {
+        // omit atime
+        { .tv_sec = 0, .tv_nsec = UTIME_OMIT },
+        mtime,
+    };
+    if (futimens(fd, times) == -1) {
+        switch (errno) {
+        case EPERM:
+            fprintf(stderr, "Warning: cannot preserve parent mtime, permission denied\n");
+            break;
+        case EROFS:
+            fprintf(stderr, "Warning: cannot preserve parent mtime, filesystem is read-only\n");
+            break;
+        default:
+            perror("Warning: futimens");
+            break;
+        }
+    }
+    close(fd);
+}
+
+#ifdef DEBUG
+#define COPYFILE_DEBUG (1<<31)
+#else
+#define COPYFILE_DEBUG (0)
+#endif
+
+int replace_with_clone(const char* src, const char* dst, bool preserve_parent_mtime) {
+    int parent_fd = -1;
+    struct timespec saved_mtime = { 0 };
+
+    if (preserve_parent_mtime &&
+        dir_mtime(dst, &parent_fd, &saved_mtime) == -1) {
+        return errno;
+    }
+
+    int result = 0;
+
     char path[PATH_MAX] = { 0 };
     if (!tmp_name(dst, path, PATH_MAX)) {
-        return errno;
+        result = errno;
+        goto cleanup;
     }
 
     errno = 0;
-    int result = genfile_clone(src, path);
+    result = genfile_clone(src, path);
 
     if (result) {
         perror("could not clonefile");
         unlink(path); // if it exists
-        return result;
+        goto cleanup;
     }
 
     if (find_zero_file(path)) {
         fprintf(stderr,
                 "invalid file created by clonefile(2)\n");
         unlink(path);
-        return ENOENT;
+        result = ENOENT;
+        goto cleanup;
     }
 
 #if defined(__APPLE__)
@@ -161,24 +233,26 @@ int replace_with_clone(const char* src, const char* dst) {
     if (check & COPYFILE_DATA) {
         perror("copyfile(3) should not copy data");
         unlink(path);
-        return check;
+        result = check;
+        goto cleanup;
     }
 
     result = copyfile(dst,
                       path,
                       NULL,
-                      COPYFILE_METADATA | (1<<31));
+                      COPYFILE_METADATA | COPYFILE_DEBUG);
     if (result) {
         perror("could not copy metadata");
         unlink(path);
-        return result;
+        goto cleanup;
     }
 
     if (find_zero_file(path)) {
         fprintf(stderr,
                 "invalid file created by copyfile(3)\n");
         unlink(path);
-        return ENOENT;
+        result = ENOENT;
+        goto cleanup;
     }
 #else
 #error Operating system not supported
@@ -191,10 +265,14 @@ int replace_with_clone(const char* src, const char* dst) {
     if (result) {
         perror("could not replace existing file");
         unlink(path);
-        return result;
+        goto cleanup;
     }
 
-    return 0;
+cleanup:
+    if (preserve_parent_mtime) {
+        restore_dir_mtime(parent_fd, saved_mtime);
+    }
+    return result;
 }
 
 
@@ -211,14 +289,25 @@ int replace_with_link(const char* src, const char* dst) {
 
 // returns a relative path to dst from src
 char* path_relative_to(const char* src, const char* dst) {
-    char* real_src = realpath(src, NULL),
-        * real_dst = realpath(dst, NULL),
-        * orig_real_src = real_src,
+    char* real_src = realpath(src, NULL);
+    if (real_src == NULL) {
+        fprintf(stderr, "%s could not be resolved to a canonical path.\n", src);
+        return NULL;
+    }
+
+    char* real_dst = realpath(dst, NULL);
+    if (real_dst == NULL) {
+        free(real_src);
+        fprintf(stderr, "%s could not be resolved to a canonical path.\n", dst);
+        return NULL;
+    }
+
+    char* orig_real_src = real_src,
         * orig_real_dst = real_dst;
 
-    // consume root /
-    real_src++;
-    real_dst++;
+    // consume root '/' if it exists
+    if (*real_src == '/') real_src++;
+    if (*real_dst == '/') real_dst++;
 
     int depth = 0;
 
@@ -275,6 +364,8 @@ char* path_relative_to(const char* src, const char* dst) {
 }
 
 int replace_with_symlink(const char* src, const char* dst) {
+    // must be called prior to unlink because realpath
+    // is used. unlinking first removes the real path
     char* path = path_relative_to(dst, src);
 
     // TODO: should this atomically move a tmp file instead of

clone.h

@@ -1,4 +1,4 @@
-// Copyright © 2023 TTKB, LLC.
+// Copyright © 2023-2026 TTKB, LLC.
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are met:
@@ -51,9 +51,28 @@
 ///   returned by `clonefile(2)`, `copyfile(2)`, or `rename(2)`.
 ///
 /// See also: `clonefile(2)`, `copyfile(2)`, or `rename(2)`
-int replace_with_clone(const char* src, const char* dst);
+int replace_with_clone(const char* src, const char* dst, bool preserve_parent_mtime);
 
+/// replace_with_link
+///
+/// The `replae_with_link` function causes the link named `dst` to be
+/// replaced with a hardlink of `src`. `src` and `dst` must be on the same
+/// volume.
+///
+/// On success `dst` will be replaced and `replace_with_link` returns 0.
+///
+/// On failure `link(2)` will return an error.
+///
+/// See also: `link(2)`
 int replace_with_link(const char* src, const char* dst);
+
+/// replace_with_symlink
+///
+/// The `replace_with_symlink` function causes the link named `dst` to be
+/// replaced with a symlink to `src`. The link will be a relative path from
+/// `dst` to `src`.
+///
+/// See also: `symlink(2)`
 int replace_with_symlink(const char* src, const char* dst);
 
 #endif // __DEDUP_CLONE_H__

dedup.1

@@ -143,6 +143,10 @@ Prevent
 .Nm
 from descending into directories that have a device number different than that
 of the file from which the descent began.
+.It Fl m , Fl Fl parent-mtime
+Preserve the parent directory modification time (mtime) when a file is cloned.
+Useful when working with backups or other programs that are sensitive to
+directory changes.
 .It Fl ? , Fl Fl help
 Print a summary of options and exit.
 .El

dedup.c

@@ -1,4 +1,4 @@
-// Copyright © 2023 TTKB, LLC.
+// Copyright © 2023-2026 TTKB, LLC.
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are met:
@@ -89,6 +89,7 @@ typedef struct DedupContext {
     bool dry_run;
     uint8_t verbosity;
     bool force;
+    bool preserve_parent_mtime;
     ReplaceMode replace_mode;
     pthread_mutex_t metrics_mutex;
     pthread_mutex_t progress_mutex;
@@ -318,7 +319,6 @@ size_t deduplicate(AList* metadata_set, DedupContext* ctx) {
         if (ctx->dry_run) {
             printf("\tcloning to %s\n",
                    fm->path);
-
             ctx->saved += fm->size;
             continue;
         }
@@ -327,7 +327,8 @@ size_t deduplicate(AList* metadata_set, DedupContext* ctx) {
         switch (ctx->replace_mode) {
         case DEDUP_CLONE:
             result = replace_with_clone(origin->path,
-                                        fm->path);
+                                        fm->path,
+                                        ctx->preserve_parent_mtime);
             break;
         case DEDUP_LINK:
             result = replace_with_link(origin->path,
@@ -374,7 +375,7 @@ size_t deduplicate(AList* metadata_set, DedupContext* ctx) {
 __attribute__((noreturn))
 static void usage(char* pgm, DedupContext* ctx) {
     fprintf(stderr,
-            "%s\nusage: %s [-I pattern] [-t n] [-PVcnvx] [-d n] [file ...]\n\n"
+            "%s\nusage: %s [-I pattern] [-t n] [-PVcmnvx] [-d n] [file ...]\n\n"
                 "Options:\n"
                 // "  --ignore, -I pattern     Exclude a pattern from being used as a clone\n"
                 // "                           source or being replaced by a clone. This option\n"
@@ -390,6 +391,8 @@ static void usage(char* pgm, DedupContext* ctx) {
                 "  --no-progress, -P        Do not display a progress bar.\n"
                 "  --threads, -t n          The number of threads to use for file building\n"
                 "                           lookup tables and replacing clones. Default: %d\n"
+                "  --parent-mtime, -m       Preserve the mtime of any parent directory\n"
+                "                           modified with a clone.\n"
                 "  --verbose, -v            Increase verbosity. May be used multiple times.\n"
                 "  --version, -V            Print the version and exit\n"
                 // "  --force, -f              Don't preserve existing hardlinks.\n"
@@ -506,7 +509,8 @@ int main(int argc, char* argv[]) {
         .done = 0,
         .dry_run = false,
         .verbosity = 0,
-        .force = 0,
+        .force = false,
+        .preserve_parent_mtime = false,
         .replace_mode = DEDUP_CLONE,
         .thread_count = cpu_count(),
         .metrics_mutex = PTHREAD_MUTEX_INITIALIZER,
@@ -525,6 +529,7 @@ int main(int argc, char* argv[]) {
         { "depth",           required_argument, NULL, 'd' },
         { "link",            no_argument,       NULL, 'l' },
         { "dry-run",         no_argument,       NULL, 'n' },
+        { "parent-mtime",    no_argument,       NULL, 'm' },
         { "symlink",         no_argument,       NULL, 's' },
         { "threads",         required_argument, NULL, 't' },
         { "verbose",         no_argument,       NULL, 'v' },
@@ -538,7 +543,7 @@ int main(int argc, char* argv[]) {
 
     int ch = -1, t;
     short d;
-    while ((ch = getopt_long(argc, argv, "I:PVc::d:fhlnst:vx?", options, NULL)) != -1) {
+    while ((ch = getopt_long(argc, argv, "I:PVc::d:fhlmnst:vx?", options, NULL)) != -1) {
         switch (ch) {
             case 'I':
                 fprintf(stderr, "-I is unimplemented\n");
@@ -567,6 +572,9 @@ int main(int argc, char* argv[]) {
             case 'l':
                 dc.replace_mode = DEDUP_LINK;
                 break;
+            case 'm':
+                dc.preserve_parent_mtime = true;
+                break;
             case 'n':
                 dc.dry_run = true;
                 break;