zx_timer_create

Summary

Create a timer.

Declaration

#include <zircon/syscalls.h>

zx_status_t zx_timer_create(uint32_t options,
                            zx_clock_t clock_id,
                            zx_handle_t* out);

Description

zx_timer_create() creates a timer, an object that can signal when a specified point in time has been reached. clock_id can be either ZX_CLOCK_MONOTONIC or ZX_CLOCK_BOOT, depending on which timeline the timer should use as its reference. Note that timers on the boot timeline will elapse during suspend-to-idle, but will not wake the system.

The options value specifies the coalescing behavior, which controls whether the system can fire the time earlier or later depending on other pending timers.

The possible values are:

  • ZX_TIMER_SLACK_CENTER
  • ZX_TIMER_SLACK_EARLY
  • ZX_TIMER_SLACK_LATE

Passing 0 in options is equivalent to ZX_TIMER_SLACK_CENTER.

See timer slack for more information.

The returned handle has the ZX_RIGHT_DUPLICATE, ZX_RIGHT_TRANSFER, ZX_RIGHT_WRITE, ZX_RIGHT_SIGNAL, ZX_RIGHT_WAIT, and ZX_RIGHT_INSPECT rights.

Rights

Caller job policy must allow ZX_POL_NEW_TIMER.

Return value

zx_timer_create() returns ZX_OK on success. In the event of failure, a negative error value is returned.

Errors

ZX_ERR_INVALID_ARGS out is an invalid pointer or NULL or options is not one of the ZX_TIMER_SLACK values or clock_id is any value other than ZX_CLOCK_MONOTONIC.

ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.

See also