Hash & dedupe files whose absolute path exceeds PATH_MAX (#117)

[martinus]

What

Actually hash and deduplicate files whose absolute path exceeds PATH_MAX (4096), instead of skipping them with a warning. This is the follow-through to #108/#115 (which only made the skip visible).

Closes #117.

Why it was non-trivial

The blocker is the kernel: open()/statx()/stat() reject any single pathname argument longer than PATH_MAX with ENAMETOOLONG. The only way to reach such a file is to open a reachable ancestor and openat-walk the remaining components, keeping every argument in range.

A useful finding shaped the design: the storage layer was already length-agnostic — the files.filename column is TEXT, the store bind uses the full string, struct filerec.filename is a heap char*, and both filerec_open() and the prune stat() act on the full string. So the full path is available at every access point, and the openat-split can be derived on demand from the flat string — no schema change and no DB_FILE_MINOR bump.

How

• New src/longpath.{c,h} — longpath_open / longpath_opendir / longpath_stat / longpath_lstat. Each reaches an over-PATH_MAX path by opening a reachable ancestor and openat-walking the rest, advancing by the longest run of components that fits one syscall argument (memrchr) rather than one component per call: a 4620-byte path costs 5 opens instead of 22. In-range paths take the plain open()/opendir()/stat() fast path internally, so callers never gate on length and the hot path is untouched.
• struct file.filename becomes a heap-owned char* (was char[PATH_MAX+1]), managed via file_set_filename() / file_cleanup() so an over-PATH_MAX path round-trips through scan and change-detection intact.
• Walk (process_dir): reaches deep directories via longpath_opendir + fdopendir, stats children relative to the directory fd, and drops the old length skip-guard.
• Filesystem probe (probe_fs): derives fs UUID, btrfs-ness and supported-ness from a single longpath_open() fd (fstatfs + statx(AT_EMPTY_PATH)), replacing the separate path-based get_uuid() / is_btrfs() / is_fs_supported() calls. The path-based is_btrfs() is deleted so it cannot be reintroduced.
• Hashing / dedupe / prune / rename-detection all route through the longpath_* helpers.
• Display and report buffers are sized from the path, not PATH_MAX: the dedupe report printed two distinct group members as identical 4096-char strings naming their parent directory. The progress slot elides via the renderer's own ellipsize_path(), so a shortened path keeps its real head and basename behind one marker.
• for_each_stdin_line() no longer bounds every consumer. -R is a SQL DELETE with no length limit, so oans -L | oans -R - previously could not remove rows the scan had just created; scan_file() keeps its own limit, where the realpath() buffer actually needs one.

Guarding the invariant

The failure mode this feature has is nasty: a reintroduced path-argument syscall gets ENAMETOOLONG, the caller reads it as "gone", the file is dropped — and the run still exits 0. Three layers guard against that:

• scripts/lint-longpath.py, wired into make lint and make check (and its own CI step). It flags any path-taking syscall in src/ that is neither dirfd-relative nor waived with a longpath-ok: <why> comment next to the code. The 23 legitimate sites (hashfile, /proc, device nodes, scan roots, the autotune sampler) each carry a one-line reason. Verified it catches the exact regression it exists to prevent.
• The invariant, its allow-list and its tests are stated in longpath.h, where anyone touching the API reads it.
• A mixed deep+shallow integration test. Every other long-path test scans a tree made only of long paths, so a silently dropped subtree looks like a pass — that blind spot is exactly what hid the probe_fs bug below.

Tests

• New C unit test builds a >PATH_MAX directory chain on tmpfs and covers open+read, opendir, stat/lstat, missing final component and missing intermediate (ENOENT, not ENAMETOOLONG), and short-path equivalence. Teardown is unconditional, so a failed assertion cannot strand the process cwd in a directory it cannot name.
• Unit tests for progress_copy_path (including degenerate caps) and for the two-stage render, pinning that a shortened path carries exactly one elision marker and keeps both ends.
• tests/integration/test_long_path.py: the deep file is hashed, dedupes (verified via a dir-fd-relative FIEMAP so the test can reach it too), no-op rescans, prunes selectively, and does not derail its in-range siblings. Covers both the deep-chain and long-basename-in-range shapes.

Verification

• make lint, scripts/verify.sh — build (no warnings), full make check, valgrind smoke: all pass.
• make integration-valgrind: clean for this change. (An unrelated, pre-existing flaky UAF in the --dedupe-options=partial drain path is filed as Flaky use-after-free in --dedupe-options=partial drain (find_dupes reads a filerec freed by dedupe_drain) #123 — measured at 7/144 findings on unmodified master and 7/144 with this branch, i.e. identical, and this PR touches neither the free nor the read side of it.)
• End-to-end on btrfs: a nested subvolume 4134 bytes deep hashes and dedupes (2 rows, 128 KiB reclaimed); before the fix the same tree printed Cannot open …: File name too long and stored 0 of its files while exiting 0.
• Benchmarks (A/B vs master, warm, interleaved, 175k-file real tree): scan perf-neutral — 12.76 s vs 12.78 s median.

Notes / out of scope (documented)

• A single root whose own realpath exceeds PATH_MAX (deep trees under a short root are fully supported). Now reported with an explicit, actionable message instead of a bare ENAMETOOLONG, and documented under NOTES in the man page.
• stdin path-list entries over PATH_MAX, and the --autotune sampler, which feeds its paths back as roots and so inherits the same limit (it now counts and reports what it skipped rather than dropping it silently).

Lifting that last limit needs a longpath_realpath() (openat the leaf O_PATH, readlink /proc/self/fd/N), which would also unblock --file-list and the sampler. Deliberately left for a follow-up.

🤖 Generated with Claude Code

[crass]

Notes / out of scope (still warned, documented)

* A single **root** whose own realpath exceeds `PATH_MAX` (deep trees under a short root are fully supported).

* stdin path-list entries over `PATH_MAX`.

I would think that these would be fairly trivial to fix after these changes. Trivial enough to include in this PR.

[crass]

I've not closely reviewed the test code.
... And it looks like the most recent push, which I didn't see until after submitting the review of the old changes, addresses some/all of my concerns.

[crass]

This if should be moved above the if block above it. This way if dirp==NULL we don't potentially leak child's memory.

[crass]

This increases openat syscalls on paths with length greater than PATH_MAX by quite a bit. You've avoided

A more efficient algorithm would be to break up the path starting at begin into maximum sized path chunks less than PATH_MAX. Then do the openat loop on each path chunk.

For the case where the file path is less than PATH_MAX, the number of syscalls will be O(1) with respect to the old code. For file paths greater than PATH_MAX, this implementation in the PR will have at least 8 times the number of openat syscalls and as much as ~2047 times the number of openat syscalls per PATH_MAX path chunk!

This also allows us rid of the fits_one_syscall checks below, which are currently needed to prevent this change from blowing up the number of syscalls for paths that are less of length less than PATH_MAX.

It would be interesting to know how much slower in wall time would be in the best worst case, absolute worst case, and my suggestions (ie. how cheap is openat).

[crass]

This would not be necessary with my suggestion above. Nor would fits_one_syscall be needed.`

[crass]

nearly all lines from this line up can be replaced with something like:

    fd = longpath_open(abspath, O_RDONLY | O_DIRECTORY | O_CLOEXEC);

[crass]

Is there a reason not to simplify the above by using strcpy instead of memcpy?
Something like:

void progress_copy_path(char *dst, size_t cap, const char *src)
{
  	size_t len;

	if (cap == 0)
		return;
	len = strlen(src);
    strncpy(dst, src + (len - (cap - 1)), cap - 1);
    if (len >= cap)
        dst[0] = '~';
}

[crass]

Ok, everything in review of the old code has been checked and does not apply for the new changes. So they can all be closed.