A file's mtime is wall-clock time: nanoseconds since the Unix epoch, UTC

[Japabu]

The owner approved this ABI change for the self-hosting track (ToyOS builds LLVM on itself, and ninja and make decide rebuilds by mtime): a file's modification time is wall-clock time, in nanoseconds, and a reboot does not change it.

The contract

toyos_abi::syscall::Stat::mtime is nanoseconds since the Unix epoch, UTC, taken off the wall clock at the write, to the resolution its mount keeps:

mount	resolution
DATA (bcachefs) and /tmp (tmpfs)	the nanosecond: the u64 is stored as given
FAT (/boot, /log)	two seconds of local time, read back as UTC nanoseconds of the even second
ROOT	undated: src/image.rs stamps 0, for a reproducible image

0 is undated. A machine whose RTC never answered has no date, so a file written there is stamped 0 and never 1970 plus uptime. std's Metadata::modified answers 0 with ErrorKind::Unsupported, the kind SYS_CLOCK_EPOCH's refusal maps to on that machine, where SystemTime::now panics. libc reports 0 as 0.

Accuracy is the RTC's second and resolution the counter's: the anchor truncates the RTC's second, as SYS_CLOCK_EPOCH already did.

The layout of Stat is unchanged (one u64), so no syscall changes. The sysroot key moves, because libc's struct stat and the std fork change.

What changed, per decision

• kernel/src/clock.rs
  • utc_nanos is the RTC's whole-second anchor carried on by the counter.
  • utc_secs (SYS_CLOCK_EPOCH) is utc_nanos / 10⁹, so the epoch syscall and a stamp cannot disagree about a second. The arithmetic is unchanged: (boot + offset)·10⁹ + nsb over 10⁹ is boot + offset + ⌊nsb/10⁹⌋.
  • mtime_now is what a write stamps: utc_nanos, or 0 with no RTC.
  • local_secs_of and mtime_of_local convert an mtime for FAT, which stores local seconds. NANOS_PER_SEC is private to the module.
• object/ops.rs, vfs.rs, revoke_selftest.rs, leak_selftest.rs stamp with mtime_now wherever they stamped nanos_since_boot: create with truncation, create of a missing file, write, ftruncate, and the flush open_backing_identified makes.
• fat32_adapter.rs
  • create and update_metadata stamp the mtime the VFS hands them. Before, they stamped the flush's instant and ignored the argument.
  • file_mtime answers UTC nanoseconds. Before, it answered local seconds, a different unit from every other mount.
  • now() stays for the stamps the VFS gives no time for: reconcile and mkdir.
• std (fork commit ac63a08077f on ToyOSOrg/rust branch wt-toyos-mtime, pinned here): Metadata::modified answers Unsupported for 0. Otherwise it already read the word as nanoseconds since UNIX_EPOCH, so it is correct now and was wrong before.
• libc
  • struct stat gets POSIX's st_atim/st_mtim/st_ctim (struct timespec), and st_mtime becomes the macro POSIX defines. fstat used to put nanoseconds into st_mtime, which is seconds.
  • st_nlink is u64, as nlink_t (unsigned long) is. The Rust Stat was 112 bytes against C's 120, so a C caller read st_blksize (0) as st_size and the stamp's tv_nsec as st_mtime, and fstat left C's last 8 bytes unwritten. That mismatch predates this branch; nothing in the tree called stat from C.

Tests

• 202_stat_mtime (C, Fast): writes 17 bytes to /tmp, then fstats and stats the file. It prints sizeof(struct stat) (120), st_size (17), whether st_mtime lies between two time(NULL) readings around the write, and whether st_mtim.tv_nsec is below a second.
• file_mtime (Rust, Fast, shared boot) judges /tmp. Each stamp must lie between two SYS_CLOCK_EPOCH readings taken around what made it: before·10⁹ ≤ mtime < (after+1)·10⁹. It covers four stamp sites:
  • two writes, the second strictly later than the first, which a clock of whole seconds cannot say;
  • File::create with no write (create with truncation);
  • OpenOptions::new().write(true).create(true) on a path shown missing first (create of a missing file);
  • a reopen of the first without truncation, then set_len(1) and sync_all (ftruncate), strictly later than its create.
• file_mtime_undated (Nightly): boots with rtc-dead and checks that the kernel refused the clock by name. It then runs file_mtime undated, which writes /tmp/file-mtime-undated without asking the time and requires modified() to fail with Unsupported.
• file_mtime_survives_a_reboot (Nightly, two boots of one DATA image):
  1. Boot 1 has the RTC staged at 2033-03-07T09:14:25 with -rtc base= and writes /home/file-mtime.bin. The printed stamp must lie within 0..300 s of that instant.
  2. With the guest gone, the host reads the same stamp off the image.
  3. Boot 2 has the RTC a day on and must read the stamp back unchanged, so a re-stamp at mount or open would show.
• toyos-fat32 a_write_time_keeps_the_even_second (host) is the pure conversion behind the FAT row: a write time drops the odd second that FatTime keeps only for creation times.

Gates

Run on the committed tree, host only; no QEMU was run.

command	exit
cargo test -p toyos-build --lib	0 (412 passed, 3 ignored)
cargo test --workspace --exclude toyos-build	0
cargo test --test toyos-build -- --list	0 (lists Fast 202_stat_mtime, Fast file_mtime, Nightly file_mtime_survives_a_reboot, Nightly file_mtime_undated)
cargo run -- --clippy	0
cargo run -- --build-only	0
202_stat_mtime.c compiled and linked by the toolchain's clang against this key's C sysroot; _Static_asserts on sizeof(struct stat) == 120, offsetof(st_size) == 48, offsetof(st_mtim) == 88	0

High-risk: ABI and filesystems

• Mutations. Each is a checked patch in the orchestrator's scratchpad (mtime-r2/). Each was applied, built with cargo run -- --build-only (EXIT=0 for all five), and reverted in the same script, leaving the tree clean. Each must turn its test red:
  • nlink-u32.patch (libc back to 32948da's layout) → 202_stat_mtime: st_size reads 0 and st_mtime reads a nanosecond count.
  • site-114.patch, site-132.patch, site-821.patch (each stamp site back to nanos_since_boot() alone) → file_mtime, on its create-with-truncation, create-of-a-missing-file and truncation cases respectively.
  • undated.patch (unwrap_or(0) → unwrap_or_else(nanos_since_boot)) → file_mtime_undated: modified() answers 1970 plus uptime.
• Negative control. negative-control.patch is git diff HEAD origin/main -- kernel toyos-abi userland/libc: the whole implementation reverted onto e3a1cdc8, except the std pin, which only changes what 0 means. It was applied, built (EXIT=0) and reverted in the same script, leaving the tree clean.
  • file_mtime goes red on its first assertion, since a stamp since boot is about 10⁹·uptime, far below before·10⁹.
  • file_mtime_undated goes red because modified() answers 1970 plus uptime.
  • file_mtime_survives_a_reboot goes red on the oracle: a drift of about −1.99·10⁹ s.
  • 202_stat_mtime goes red by not compiling, because main's header has no st_mtim.
• Independent oracle. The instant the host stages in the emulated RTC with -rtc base=, the same oracle wall_clock_* uses. For the C layout, clang's own sizeof/offsetof over the header.

What I am unsure of

• An undated machine stamps every file 0, so the shared-object cache's BackingId (size plus mtime) no longer sees a same-size rewrite on any mount there. Before, nanos_since_boot kept two writes apart. Filed: issues/isolation/the-so-caches-identity-is-blind-on-an-undated-machine.md.
• FAT cannot store undated. FatTime::from_unix_secs clamps 0 to 1980-01-01, which reads back as a date. Filed: issues/filesystem/an-undated-file-on-fat-reads-back-as-1980.md.
• Userland reads the wall clock in whole seconds. std's SystemTime::now and libc's clock_gettime do, so a just-written file can read as up to a second in the future against the program's own "now". Filed: issues/filesystem/userlands-wall-clock-has-whole-seconds-and-an-mtime-has-nanoseconds.md.

When merging

#583 and #536 land first.

• Loader slimming stage 1: the RTC is UTC, KernelArgs refuses another layout by name, IA32_TSC_ADJUST moves to the kernel #583 (UTC-only RTC):
  • clock.rs: utc_nanos = BOOT_SECS·10⁹ + nanos_since_boot(), and utc_secs stays utc_nanos / 10⁹. Delete local_secs_of and mtime_of_local, and stamp's and file_mtime's calls to them if fat32_adapter.rs still exists.
  • tests/toyos.rs: take Loader slimming stage 1: the RTC is UTC, KernelArgs refuses another layout by name, IA32_TSC_ADJUST moves to the kernel #583's side of the wall_clock_zone rows.
• Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536 (fsd):
  • fat32_adapter.rs: take the delete and drop the whole hunk.
  • vfs.rs: the open_backing_identified flush hunk goes with Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536.
  • ops.rs: Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536's four nanos_since_boot() stamps (its :115, :133, :536 before touch, :779 before touch) become mtime_now(), and so does revoke_selftest.rs:21. Take Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536's leak_selftest.rs.
  • Stat::mtime's doc: DATA's resolution becomes the second, because fsd stamps off SYS_CLOCK_EPOCH's whole seconds. Say so there, citing issues/filesystem/userlands-wall-clock-has-whole-seconds-and-an-mtime-has-nanoseconds.md.
  • the-last-handle-to-close-stamps-the-file-with-its-own-mtime.md: judge it again against file_cache::touch, and delete it if that closes it. a-fat-files-mtime-reads-finer-through-its-writer-than-after-a-reopen.md and an-undated-file-on-fat-reads-back-as-1980.md: the mechanism becomes fsd's.

Closes issues/filesystem/a-files-mtime-is-nanoseconds-since-boot.md. Also filed, found by the audit and not fixed here:

• issues/filesystem/the-last-handle-to-close-stamps-the-file-with-its-own-mtime.md, which reaches FAT as well since this change.
• issues/filesystem/a-fat-files-mtime-reads-finer-through-its-writer-than-after-a-reopen.md
• issues/filesystem/std-calls-undated-what-it-did-not-stat.md: DirEntry::metadata answers 0 for a file the kernel has a stamp for, and set_times returns Ok having set nothing.

🤖 Generated with Claude Code

[Japabu]

Review, round 1, at 32948da

Ready for review. CI host concluded success on 32948da (run 36473365989; the earlier run 36472224038 was skipped). The orchestrator's guest runs at 32948da exited 0: file_mtime, file_mtime_survives_a_reboot, kernel_log_file, wall_clock_zone and Fast. The whole-change control exited 1 on both new tests, for the named reason. git merge-tree --write-tree origin/main 32948daf is clean. Net size: +396/−27. Production is +80/−27 (kernel +57/−20, toyos-abi +6/−1, libc +18/−7), tests +225, issues +91.

BLOCKER

• userland/libc/src/posix_io.rs:488: st_nlink: u32 does not match nlink_t = unsigned long (include/sys/types.h:14). The Rust Stat is 112 bytes with st_mtim at offset 80, and C's struct stat is 120 bytes with st_mtim at 88. So a C caller's st_mtime reads the stamp's tv_nsec, and its st_size (offset 48) reads st_blksize, which is 0. fstat also leaves C's last 8 bytes unwritten. The PR's libc claim is false, and no C source in the tree calls stat or fstat, so nothing measures it. Fix: st_nlink: u64. Add a C test to tests/testcases that writes N bytes, then fstats and stats the file, and asserts sizeof(struct stat) == 120, st_size == N, before <= st_mtime <= time(NULL) and 0 <= st_mtim.tv_nsec < 1000000000. It must be red at 32948da.
• kernel/src/object/ops.rs:114,132,821: three of the four stamp sites the PR names can each go back to crate::clock::nanos_since_boot() and every test stays green. The sites are create with truncate, create of a missing file, and ftruncate. file_mtime always writes after it creates, so only :526 is observed, and nothing calls ftruncate. Apply each patch alone: replace crate::clock::mtime_now() with crate::clock::nanos_since_boot() at :114, at :132 and at :821. Tests that must turn them red, in file_mtime's shared arm, each checked against write_judged's window:
  • (a) File::create with no write, then stat;
  • (b) OpenOptions::new().write(true).create(true) on a missing path, with no write;
  • (c) reopen (a) without truncation, set_len(1), sync_all; its stamp must also be strictly later than (a)'s.
    These sites survive Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536 (its ops.rs:115,133,779).
• kernel/src/clock.rs:202: the contract's no-RTC clause, which the ABI doc repeats, has no test. unwrap_or_else(nanos_since_boot) → unwrap_or(0) passes every run. The test: a file_mtime mode that never calls SYS_CLOCK_EPOCH, run on the rtc-dead machine (wall_clock_rtc_dead's params). It writes /tmp twice and asserts 0 < first < second < 86_400·10⁹. It must be red under the patch.

NOTE

• kernel/src/clock.rs:202: on an RTC-dead machine the no-RTC clause makes SYS_FSTAT answer 1970 plus uptime. wallclock::undated calls a 1970 answer "the defect this whole shape exists to make impossible", and std's SystemTime::now panics rather than answer 1970. The owner approved this per the brief; put the contradiction to him by name.
• kernel/src/fat32_adapter.rs:1054: FAT now stores the flushing handle's mtime instead of the flush instant. So the last-handle defect this PR files now reaches FAT, which it did not before, and the issue does not say so. Take this example: a writer at t1 closes, then a reader opened at t0 closes last; the file is stamped t0. The file goes in Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536. If the landing order changes, this is a BLOCKER.
• kernel/src/fat32_adapter.rs:925: no test checks the unit file_mtime answers. Dropping * crate::clock::NANOS_PER_SEC (the old defect) stays green, because no test stats a FAT file. The file goes in Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536.
• kernel/src/clock.rs:185: pub const NANOS_PER_SEC sits beside the literal 1_000_000_000 at :160 and :175. After Loader slimming stage 1: the RTC is UTC, KernelArgs refuses another layout by name, IA32_TSC_ADJUST moves to the kernel #583 and Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536 its only users are in clock.rs, so make it private and use it everywhere or not at all.
• What the merge of Loader slimming stage 1: the RTC is UTC, KernelArgs refuses another layout by name, IA32_TSC_ADJUST moves to the kernel #583 must change:
  • clock.rs: utc_nanos = BOOT_SECS·10⁹ + nanos_since_boot(), and utc_secs stays utc_nanos / 10⁹. Delete local_of_utc and utc_of_local, and stamp's and file_mtime's calls to them.
  • tests/toyos.rs: take Loader slimming stage 1: the RTC is UTC, KernelArgs refuses another layout by name, IA32_TSC_ADJUST moves to the kernel #583's side of the wall_clock_zone rows.
• What the merge of Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536 must change:
  • fat32_adapter.rs: take the delete, and drop the whole hunk.
  • vfs.rs: the open_backing_identified flush hunk goes with Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536.
  • ops.rs: Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536's four nanos_since_boot() stamps (:115, :133, :536 before touch, :779 before touch) become mtime_now(), and so does revoke_selftest.rs:21. Take Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536's leak_selftest.rs.
• Also on the Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536 merge: fsd's volume::now_nanos stamps clock_epoch whole seconds, and 0 when no RTC answered. So on DATA and FAT the stamp has second resolution, and the no-RTC clause is false. Either fsd follows the contract, or the Stat::mtime doc says only what holds. file_mtime_survives_a_reboot passes at whole seconds, so it cannot tell the two apart.
• issues/filesystem/the-last-handle-to-close-stamps-the-file-with-its-own-mtime.md: its mechanism (writeback.rs, the enqueue on the last close) is deleted by Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536, and file_cache::touch moves the mtime to the file. Judge the issue again at that merge and delete it if it is closed. a-fat-files-mtime-reads-finer-through-its-writer-than-after-a-reopen.md cites fat32_adapter.rs's stamp; at that merge the mechanism is fsd's.

REMOVE

• toyos-abi/src/syscall.rs:689: "— never a time since boot" contradicts the no-RTC clause two lines below it.
• toyos-abi/src/syscall.rs:690-694: the three path citations (kernel/src/fat32_adapter.rs, src/image.rs, kernel/src/clock.rs's mtime_now); the first rots at Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536.
• kernel/src/clock.rs:178-180: "so a file written after this answered s carries a stamp of at least s seconds" is false on FAT, which stores an odd second as s − 1.
• tests/toyos.rs:1352: the comment restates file_mtime_survives_a_reboot's doc.
• tests/toyos-rust-tests/src/bin/file_mtime.rs:8-10: the sentence from "file_mtime_survives_a_reboot" on narrates another file.
• issues/isolation/the-so-caches-refusals-are-narrower-than-its-reach.md:17-18: "the mtime is nanos_since_boot at the flush" is false from this change on.
• PR body, "PR Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536's fsd already meets this contract" paragraph: false, because fsd stamps whole seconds and 0 with no RTC.
• PR body, "sshd's SFTP attributes read modified() and now report real times": unmeasured.
• PR body, the second oracle ("the host's own bcachefs reader … no kernel code involved"): it is the in-tree crate the kernel writes DATA with, so it is not independent.
• PR body, "Guest runs to queue", and the Loader slimming stage 1: the RTC is UTC, KernelArgs refuses another layout by name, IA32_TSC_ADJUST moves to the kernel #583/Storage: file servers for DATA, the log and the boot volume; the kernel's NVMe and FAT go #536 bullets under "What I am unsure of": process notes that rot at the merge.

SEND BACK

[Japabu]

Round 2, head 57cc41e: gh pr view 587 --json mergeable returns CONFLICTING against origin/main 0368861. git merge-tree --write-tree origin/main 57cc41e4 exits 1 with a content conflict in tests/testcases/LICENSE. host passes on 57cc41e, but it is not measured against the tree this branch would merge into.

NOT READY FOR REVIEW