Many filesystems support mtime (modification time) as an attribute on files. Intuitively, mtime is updated when a file's contents change, but intuition is easily beguiled and the actual semantics of mtime are much more subtle. This document describes the semantics of mtime on Fuchsia filesystems.
Warning: The semantics described in this document aren‘t implemented yet. This document serves as a contract for ongoing implementation work. If you come across this document and don’t work on Storage, please ask us about the current state of mtime affairs, rather than assuming this document is an accurate description of the current state.
The following properties are guaranteed for mtime on Fuchsia:
fsync or the next reboot (graceful or not), mtime is guaranteed to be updated at least once. That said, the value of mtime is not guaranteed to change in this update; see non-monotinicity below.None of the following are guaranteed properties of mtime on Fuchsia:
Mtime is not guaranteed to be updated for every write to a file. Concretely, in the presence of a writeback cache, several writes to a file may be queued up and flushed together at a later time; in this case only one mtime update would need to be performed.
Mtime being updated does not guarantee that its corresponding file write was persisted to disk. If the filesystem exits uncleanly, it is possible for an mtime update to be observed without the write that induced that mtime update.
Concretely, the following scenario is possible:
write(…); // A fstat(…); // <-- see time T1 write(…); // B fstat(…); // <-- see time T2 // Later, after an ungraceful shutdown read(…); // <-- see A read(…); // <- Don't see B stat(…); // see time T2
Mtime is not guaranteed to be monotonically increasing. In practice, Fuchsia-native filesystems use the UTC time source, which does not guarantee monotonicity; see https://fuchsia.dev/fuchsia-src/concepts/time/utc/behavior.
Mtime has no guaranteed time precision. In practice, Fuchsia-native filesystems use Zircon time objects which are nanosecond granularity, but there is no requirement for filesystems to store nanosecond-granularity timestamps.
Mtime is not guaranteed to match the time source that an application has access to. In practice, Fuchsia-native filesystems use the system UTC time source, but it is possible for components (or the filesystem) to use arbitrary time sources and there is no requirement for these time sources to be in sync.
The VFS should generally drive the policy of when to update mtime, and filesystems should offer a mechanism to update the mtime on a file.
Ideally, filesystems should offer the ability to atomically update mtime with a file write. If this is not possible, the filesystem should ensure (via journalling) that the mtime update is persisted whenever the write is persisted (i.e. it should not be possible to observe the write without the mtime update).
In the future, when we have writeback caching, the VFS will send one or more writes to the filesystem as part of the asynchronous flush of cached writes. The first of these writes for a given file (during a given cache flush) should update the file mtime.