# zx_clock_read_mapped

## Summary

Perform a basic read of a mapped clock's state. Behaves identically to a call to
[`zx_clock_read()`](https://fuchsia.dev/reference/syscalls/clock_read), however it operates on a mapped clock's state instead of a clock
handle, and may offer performance benefits as it usually does not need to enter the Zircon
kernel in order to perform the read. See [mappable clocks](https://fuchsia.dev/docs/reference/kernel_objects/clock#mappable_clocks) for more details.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_clock_read_mapped(const void* clock_addr, zx_time_t* now);

## Rights

No handle is needed in order to perform a successful read, therefore no specific handle
rights are needed either. Instead, the user must provide the virtual address of a currently
valid clock state mapping, established using [`zx_vmar_map_clock()`](https://fuchsia.dev/reference/syscalls/vmar_map_clock)

## Description

Perform a basic read of the clock's mapped state, and return its current time in the
*now* out parameter.

## Return value

On success, returns `ZX_OK` along with the clock's current time in the *now* output
parameter.

## Errors

Any attempt to pass a virtual pointer for `clock_addr` which was:

- Not the value returned by the original call to `zx_clock_map()`.
- A pointer to clock state which has been either partially, or completely, unmapped.

Will result in undefined behavior.

## See also

- [clocks](https://fuchsia.dev/docs/reference/kernel_objects/clock)
- [mappable clocks](https://fuchsia.dev/docs/reference/kernel_objects/clock#mappable_clocks)
- [`zx_clock_create()`](https://fuchsia.dev/reference/syscalls/clock_create)
- [`zx_clock_read()`](https://fuchsia.dev/reference/syscalls/clock_read)
- [`zx_clock_get_details_mapped()`](https://fuchsia.dev/reference/syscalls/clock_get_details_mapped)
- [`zx_vmar_map_clock()`](https://fuchsia.dev/reference/syscalls/vmar_map_clock)