src/storage/docs/mtime.md

# Modification Time Semantics

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.

## Properties of modification time

The following properties are guaranteed for mtime on Fuchsia:

* If at least one write to a file is persisted to disk before the next `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:

  ```c
  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.

## Suggested implementation of mtime in Fuchsia filesystems

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.