1# zx_object_wait_one
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7object_wait_one - wait for signals on an object
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_object_wait_one(zx_handle_t handle,
17                               zx_signals_t signals,
18                               zx_time_t deadline,
19                               zx_signals_t* observed);
20```
21
22## DESCRIPTION
23
24`zx_object_wait_one()` is a blocking syscall which causes the caller to
25wait until either the *deadline* passes or the object to which *handle* refers
26asserts at least one of the specified *signals*. If the object is already
27asserting at least one of the specified *signals*, the wait ends immediately.
28
29Upon return, if non-NULL, *observed* is a bitmap of *all* of the
30signals which were observed asserted on that object while waiting.
31
32The *observed* signals may not reflect the actual state of the object's
33signals if the state of the object was modified by another thread or
34process.  (For example, a Channel ceases asserting **ZX_CHANNEL_READABLE**
35once the last message in its queue is read).
36
37The *deadline* parameter specifies a deadline with respect to
38**ZX_CLOCK_MONOTONIC**.  **ZX_TIME_INFINITE** is a special value meaning wait
39forever.
40
41## RIGHTS
42
43<!-- Updated by update-docs-from-abigen, do not edit. -->
44
45*handle* must have **ZX_RIGHT_WAIT**.
46
47## RETURN VALUE
48
49`zx_object_wait_one()` returns **ZX_OK** if any of *signals* were observed
50on the object before *deadline* passes.
51
52In the event of **ZX_ERR_TIMED_OUT**, *observed* may reflect state changes
53that occurred after the deadline passed, but before the syscall returned.
54
55In the event of **ZX_ERR_CANCELED**, *handle* has been closed,
56and *observed* will have the **ZX_SIGNAL_HANDLE_CLOSED** bit set.
57
58For any other return value, *observed* is undefined.
59
60## ERRORS
61
62**ZX_ERR_INVALID_ARGS**  *observed* is an invalid pointer.
63
64**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
65
66**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_WAIT** and may
67not be waited upon.
68
69**ZX_ERR_CANCELED**  *handle* was invalidated (e.g., closed) during the wait.
70
71**ZX_ERR_TIMED_OUT**  The specified deadline passed before any of the specified
72*signals* are observed on *handle*.
73
74**ZX_ERR_NOT_SUPPORTED**  *handle* is a handle that cannot be waited on
75(for example, a Port handle).
76
77## SEE ALSO
78
79 - [`zx_object_wait_async()`]
80 - [`zx_object_wait_many()`]
81
82<!-- References updated by update-docs-from-abigen, do not edit. -->
83
84[`zx_object_wait_async()`]: object_wait_async.md
85[`zx_object_wait_many()`]: object_wait_many.md
86