docs/concepts/kernel/time/language_support.md

# Time language support

This page details how you can handle time when developing software on Fuchsia.

In general, you may use any time library available for your language. Most
libraries are able to link against [Fuchsia's libc implementation][libc] to
obtain time. It is recommended that you use a platform-agnostic library unless
you need Fuchsia specific time operations.

Various time options are available, such as:

Language | Monotonic | UTC
-------- | --------- | ---
C | [`clock_gettime`][c-clock-gettime]{:.external} | [`time`][c-time]{:.external}
C++ | [`std::chrono::steady_clock`][cpp-steady-clock]{:.external} | [`std::chrono::system_clock`][cpp-system-clock]{:.external}
Rust | [`std::time::Instant`][rust-instant]{:.external} | [`std::time::SystemTime`][rust-system-time]{:.external}

## Fuchsia specific time operations

In some cases, you will need to handle time in a Fuchsia specific manner. This
is necessary when you need to handle Fuchsia's representation of time directly,
or when you need to handle
[Fuchsia specific UTC behavior][fuchsia-utc-behavior].

### Monotonic time

Monotonic time on Fuchsia is represented as a signed 64 bit integer, which
contains the number of nanoseconds since the system was powered on. See
[`zx_clock_get_monotonic`][zx-monotonic] for more details.

* {C }

  Monotonic time is accessible through [libzircon][c-libzircon].

  ```c
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="common_imports" adjust_indentation="auto" %}

  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="monotonic" adjust_indentation="auto" %}
  ```

* {C++}

  Monotonic time is accessible through [libzx][cpp-libzx].

  ```cpp
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="common_imports" adjust_indentation="auto" %}

  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="monotonic" adjust_indentation="auto" %}
  ```

* {Rust}

  Monotonic time is accessible through the [zx][rust-zircon] crate.
  This crate is only available in-tree.

  ```rust
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/rust/src/main.rs" region_tag="monotonic" adjust_indentation="auto" %}
  ```

### UTC time

UTC time on Fuchsia is represented as a signed 64 bit integer that contains
the number of nanoseconds since the Unix epoch (January 1st, 1970).

Operations on the UTC clock require obtaining a handle to the UTC clock
provided to the runtime.

Handling the UTC clock directly enables a few Fuchsia specific operations,
including:

* Inspecting the UTC clock's properties.
* Waiting for the UTC clock to begin running, which indicates it has been
synchronized, before reading it.

* {C }

  You can obtain a handle to the UTC clock using `zx_utc_reference_get` and use
  the syscalls exposed in [libzircon][c-libzircon].

  ```c
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="common_imports" adjust_indentation="auto" %}
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="utc_imports" adjust_indentation="auto" %}

  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="utc" adjust_indentation="auto" %}
  ```

* {C++}

  You can obtain a handle to the UTC clock using `zx_utc_reference_get` and use
  the syscall wrappers in [libzx][cpp-libzx].

  ```cpp
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="common_imports" adjust_indentation="auto" %}
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="utc_imports" adjust_indentation="auto" %}

  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="utc" adjust_indentation="auto" %}
  ```

* {Rust}

  You can obtain a handle to the UTC clock using the
  [fuchsia_runtime][rust-runtime] crate and use the syscall wrappers in the
  [zx][rust-zircon] crate. The [fuchsia_async][rust-async] crate
  contains utilities to aid waiting for the clock to start. Note that these
  crates are only available in-tree.

  ```rust
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/rust/src/main.rs" region_tag="utc" adjust_indentation="auto" %}
  ```

[libc]: /docs/development/languages/c-cpp/libc.md
[c-clock-gettime]: https://linux.die.net/man/3/clock_gettime
[c-time]: https://linux.die.net/man/2/time
[cpp-steady-clock]: https://en.cppreference.com/w/cpp/chrono/steady_clock
[cpp-system-clock]: https://en.cppreference.com/w/cpp/chrono/system_clock
[rust-instant]: https://doc.rust-lang.org/std/time/struct.Instant.html
[rust-system-time]: https://doc.rust-lang.org/std/time/struct.SystemTime.html
[fuchsia-utc-behavior]: utc/behavior.md#differences_from_other_operating_systems
[zx-monotonic]: /reference/syscalls/clock_get_monotonic.md
[c-libzircon]: /docs/concepts/process/core_libraries.md#libzircon
[cpp-libzx]: /docs/concepts/process/core_libraries.md#libzx
[rust-runtime]: /src/lib/fuchsia-runtime
[rust-zircon]: /sdk/rust/zx
[rust-async]: /src/lib/fuchsia-async