zx_clock_create

NAME

Create a new clock object.

SYNOPSIS

#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 for an overview of clock objects.

Options

Two options are currently defined for clock objects.

  • ZX_CLOCK_OPT_MONOTONIC : When set, creates a clock object which is guaranteed to never run backwards. Monotonic clocks must always move forward.
  • ZX_CLOCK_OPT_CONTINUOUS : When set, creates a clock which 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.

Arguments

One additional creation-time argument may be specified when configuring the clock, the backstop time. See clocks 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 and ZX_RIGHT_WRITE rights assigned to them.

ERRORS

  • ZX_ERR_INVALID_ARGS : An invalid option flag was specified, a bad args structure version/pointer was passed, or ZX_CLOCK_OPT_CONTINUOUS was specified without also specifying ZX_CLOCK_OPT_MONOTONIC.
  • ZX_ERR_NO_MEMORY Failure due to lack of memory.

SEE ALSO