docs/syscalls/timer_set.md

# zx_timer_set

## NAME

timer_set - start a timer

## SYNOPSIS

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

zx_status_t zx_timer_set(zx_handle_t handle, zx_time_t deadline,
                         zx_duration_t slack);

```

## DESCRIPTION

**zx_timer_set**() starts a one-shot timer that will fire when
*deadline* passes. If a previous call to **zx_timer_set**() was
pending, the previous timer is canceled and
**ZX_TIMER_SIGNALED** is de-asserted as needed.

The *deadline* parameter specifies a deadline with respect to
**ZX_CLOCK_MONOTONIC**. To wait for a relative interval,
use **zx_deadline_after**() returned value in *deadline*.

To fire the timer immediately pass a *deadline* less than or equal to **0**.

When the timer fires it asserts **ZX_TIMER_SIGNALED**. To de-assert this
signal call **timer_cancel**() or **timer_set**() again.

The *slack* parameter specifies a range from *deadline* - *slack* to
*deadline* + *slack* during which the timer is allowed to fire. The system
uses this parameter as a hint to coalesce nearby timers.

The precise coalescing behavior is controlled by the *options* parameter
specified when the timer was created. **ZX_TIMER_SLACK_EARLY** allows only
firing in the *deadline* - *slack* interval and **ZX_TIMER_SLACK_LATE**
allows only firing in the *deadline* + *slack* interval. The default
option value of 0 is **ZX_TIMER_SLACK_CENTER** and allows both early and
late firing with an effective interval of *deadline* - *slack* to
*deadline* + *slack*

## RIGHTS

*handle* must have **ZX_RIGHT_WRITE**.

## RETURN VALUE

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


## ERRORS

**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.

**ZX_ERR_ACCESS_DENIED**  *handle* lacks the right **ZX_RIGHT_WRITE**.

**ZX_ERR_OUT_OF_RANGE**  *slack* is negative.

## SEE ALSO

[timer_create](timer_create.md),
[timer_cancel](timer_cancel.md),
[deadline_after](deadline_after.md)