docs/concepts/kernel/time/overview.md

# Time Overview

Components on Fuchsia can read current time using four different
[time standards][1]:

* **[Monotonic](monotonic.md)**: Monotonic time is a measurement of the time
  since the system was powered on, not including time spent in Suspend-to-Idle.
  Monotonic time always moves forwards and is always available to all
  applications but is only meaningful with the context of a single power cycle
  on a single Fuchsia device.
* **[Boot](boot.md)**: Boot time is a measurement of the time since the system
  was powered on including any time spent in Suspend-to-Idle. Like monotonic
  time, boot time always moves forward, is always available, and is only
  meaningful with the context of a single power cycle on a single Fuchsia
  device.
* **[UTC](utc/overview.md)**: UTC time is the system’s best estimate of
  [Coordinated Universal Time][2]. UTC is usually acquired over a network
  so there are conditions under which the system may not know UTC. Developers
  using UTC should pay particular attention to [UTC behavior](utc/behavior.md)
  to understand the unique properties of UTC on Fuchsia.
* **[Local](local.md)**: Local time is the system’s best estimate of the
  [standard time][3] at the device’s location, aka "wall clock time". Local time
  is derived from UTC and time zone, so inherits much of the
  [UTC behavior](utc/behavior.md). There are conditions under which local time
  is not available. The local time will jump substantially if the user changes
  time zone.

These time standards are frequently available through the
[time functions in supported languages](language_support.md) in addition to
[time syscalls](/reference/syscalls/clock_create.md).

As a developer, you must select the most appropriate time standard to address
each problem. We recommend using monotonic time unless your program needs
to be aware of time spent in Suspend-To-Idle. Boot time is recommended if
timestamps must be kept in sync with underlying hardware or external services,
and monotonicity is required. UTC can be used if timestamps must be
correlated with external services and monotonicity is not required. Local time,
as a derivative of UTC time, is generally only used in UX applications.

For example:

1. Use monotonic time to implement a ten second delay between retries.
   Monotonic time will be available in all cases so provides the simplest and
   most reliable solution.
1. Use boot time to timestamp trace points in Fuchsia, as traces should display
   time spent suspended and cannot have their timeline jump back and forth.
1. Use UTC time to expire and delete a file stored on disk after seven days.
   Here monotonic time would not allow the expiry time to be
   preserved across power cycles and local time would have coupled the
   correctness of the expiry to the timezone setting.
1. Use UTC time to timestamp an on-device event that will be read by some
   server. In this case monotonic time would not work since the server probably
   does not know when the Fuchsia device last powered on. Using local time would
   require that the device and server agree on the timezone, which would be error
   prone.
1. Use local time to display the current time to the user as an analog clock
   face. Local time is most natural time standard for users so no other time
   standards are practical here.

Testing code that depends on time can be difficult on any platform. Tools and
best practices for testing time dependencies on Fuchsia are being developed and
will be linked here when available.

[1]: https://en.wikipedia.org/wiki/Time_standard
[2]: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
[3]: https://en.wikipedia.org/wiki/Standard_time