# zx_clock_create

## Summary

Create a new clock object.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_clock_create(uint64_t options,
                                const void* args,
                                zx_handle_t* out);

## Rights

None.

## Description

Creates a new zircon clock object. See [clocks](https://fuchsia.dev/docs/reference/kernel_objects/clock) for an
overview of clock objects.

### Options

The following options are defined for clock objects:

- `ZX_CLOCK_OPT_BOOT`: When set, creates a clock object whose reference is the boot timeline.
- `ZX_CLOCK_OPT_MONOTONIC` : When set, creates a clock object that is guaranteed to never run backwards. Monotonic clocks must always move forward.
- `ZX_CLOCK_OPT_CONTINUOUS` : When set, creates a clock that is guaranteed to never jump either forwards or backwards. Continuous clocks may only be maintained using frequency adjustments and are, by definition, also monotonic. Attempting to create a clock object with the `ZX_CLOCK_OPT_CONTINUOUS` option specified, but without the `ZX_CLOCK_OPT_MONOTONIC` option specified is an error, which will be signalled with `ZX_ERR_INVALID_ARGS`.
- `ZX_CLOCK_OPT_AUTO_START` : When set, creates a clock that is started automatically for the user. You don't need to call zx_clock_update() to start the clock running. Initially, the clock will be a clone of clock monotonic, meaning that the internal transformation from clock monotonic to the newly created synthetic clock is the identity function. The created clock does not have to be created with either the `ZX_CLOCK_OPT_MONOTONIC` or `ZX_CLOCK_OPT_CONTINUOUS` flags set, however. Once created, users may still update the clock within the limits defined by the monotonic and continuous properties specified at create time, the handle rights, and the backstop time of the clock.
- `ZX_CLOCK_OPT_MAPPABLE` : When set, creates a clock that can be turned into a memory-mapped clock using `zx_vmar_map_clock()`. See [mappable clocks](https://fuchsia.dev/docs/reference/kernel_objects/clock#mappable_clocks) for more details.

### Arguments

One additional creation-time argument may be specified when configuring the clock, the backstop
time. See [clocks](https://fuchsia.dev/docs/reference/kernel_objects/clock) for more details about backstop times.

In order to configure a backstop time, a user must pass a `zx_clock_create_args_v1_t` structure to
the `zx_clock_create` call via the `args` parameter. Additionally, the `options` bits must have
`ZX_CLOCK_ARGS_VERSION(1)` set in them.

For example, a user who wished to create a monotonic clock with a backstop time of 5500 might do
something like the following.

    #include <zircon/syscalls.h>
    #include <zircon/syscalls/clock.h>

    zx_handle_t MakeAClock() {
      zx_clock_create_args_v1_t args;
      zx_handle_t the_clock;
      zx_status_t status;

      args.backstop_time = 5500;
      status = zx_clock_create(ZX_CLOCK_ARGS_VERSION(1) | ZX_CLOCK_OPT_MONOTONIC, &args, &the_clock);
      if (status != ZX_OK) {
        // Log the error
        return ZX_HANDLE_INVALID;
      }

      return the_clock;
    }

Users do not have to supply an arguments structure. If an explicit backstop is not required, users
may omit the version bits from the options parameter and simply pass nullptr for args.

## Return value

On success, returns `ZX_OK` along with a new clock object via the *out*
handle. Handles to newly created clock objects will have the `ZX_RIGHT_READ`,
`ZX_RIGHT_WRITE` and `ZX_RIGHT_SIGNAL` rights assigned to them.

## Errors

- `ZX_ERR_INVALID_ARGS` : An invalid option flag was specified, a bad args structure version or pointer was passed, `ZX_CLOCK_OPT_CONTINUOUS` was specified without also specifying `ZX_CLOCK_OPT_MONOTONIC`, or the initial backstop time of an automatically started clock is after the current clock monotonic time.
- `ZX_ERR_NO_MEMORY` Failure due to lack of memory.

## See also

- [clocks](https://fuchsia.dev/docs/reference/kernel_objects/clock)
- [`zx_clock_get_details()`](https://fuchsia.dev/reference/syscalls/clock_get_details)
- [`zx_clock_read()`](https://fuchsia.dev/reference/syscalls/clock_read)
- [`zx_clock_update()`](https://fuchsia.dev/reference/syscalls/clock_update)