1# zx_timer_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7timer_create - create a timer
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_timer_create(uint32_t options,
17                            zx_clock_t clock_id,
18                            zx_handle_t* out);
19```
20
21## DESCRIPTION
22
23`zx_timer_create()` creates a timer, an object that can signal
24when a specified point in time has been reached. The only valid
25*clock_id* is **ZX_CLOCK_MONOTONIC**.
26
27The *options* value specifies the coalescing behavior which
28controls whether the system can fire the time earlier or later
29depending on other pending timers.
30
31The possible values are:
32
33+ **ZX_TIMER_SLACK_CENTER** coalescing is allowed with earlier and
34  later timers.
35+ **ZX_TIMER_SLACK_EARLY** coalescing is allowed only with earlier
36  timers.
37+ **ZX_TIMER_SLACK_LATE** coalescing is allowed only with later
38  timers.
39
40Passing 0 in options is equivalent to **ZX_TIMER_SLACK_CENTER**.
41
42The returned handle has the **ZX_RIGHT_DUPLICATE**, **ZX_RIGHT_TRANSFER**,
43**ZX_RIGHT_READ** and **ZX_RIGHT_WRITE** right.
44
45## RIGHTS
46
47<!-- Updated by update-docs-from-abigen, do not edit. -->
48
49TODO(ZX-2399)
50
51## RETURN VALUE
52
53`zx_timer_create()` returns **ZX_OK** on success. In the event
54of failure, a negative error value is returned.
55
56## ERRORS
57
58**ZX_ERR_INVALID_ARGS**  *out* is an invalid pointer or NULL or
59*options* is not one of the **ZX_TIMER_SLACK** values or *clock_id* is
60any value other than **ZX_CLOCK_MONOTONIC**.
61
62**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
63There is no good way for userspace to handle this (unlikely) error.
64In a future build this error will no longer occur.
65
66## SEE ALSO
67
68 - [`zx_deadline_after()`]
69 - [`zx_handle_close()`]
70 - [`zx_timer_cancel()`]
71 - [`zx_timer_set()`]
72
73<!-- References updated by update-docs-from-abigen, do not edit. -->
74
75[`zx_deadline_after()`]: deadline_after.md
76[`zx_handle_close()`]: handle_close.md
77[`zx_timer_cancel()`]: timer_cancel.md
78[`zx_timer_set()`]: timer_set.md
79