1# zx_object_wait_one
2
3## NAME
4
5object_wait_one - wait for signals on an object
6
7## SYNOPSIS
8
9```
10#include <zircon/syscalls.h>
11
12zx_status_t zx_object_wait_one(zx_handle_t handle,
13                               zx_signals_t signals,
14                               zx_time_t deadline,
15                               zx_signals_t* observed);
16```
17
18## DESCRIPTION
19
20**object_wait_one**() is a blocking syscall which causes the caller to
21wait until either the *deadline* passes or the object to which *handle* refers
22asserts at least one of the specified *signals*. If the object is already
23asserting at least one of the specified *signals*, the wait ends immediately.
24
25Upon return, if non-NULL, *observed* is a bitmap of *all* of the
26signals which were observed asserted on that object while waiting.
27
28The *observed* signals may not reflect the actual state of the object's
29signals if the state of the object was modified by another thread or
30process.  (For example, a Channel ceases asserting **ZX_CHANNEL_READABLE**
31once the last message in its queue is read).
32
33The *deadline* parameter specifies a deadline with respect to
34**ZX_CLOCK_MONOTONIC**.  **ZX_TIME_INFINITE** is a special value meaning wait
35forever.
36
37## RIGHTS
38
39TODO(ZX-2399)
40
41## RETURN VALUE
42
43**object_wait_one**() returns **ZX_OK** if any of *signals* were observed
44on the object before *deadline* passes.
45
46In the event of **ZX_ERR_TIMED_OUT**, *observed* may reflect state changes
47that occurred after the deadline passed, but before the syscall returned.
48
49For any other return value, *observed* is undefined.
50
51## ERRORS
52
53**ZX_ERR_INVALID_ARGS**  *observed* is an invalid pointer.
54
55**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
56
57**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_WAIT** and may
58not be waited upon.
59
60**ZX_ERR_CANCELED**  *handle* was invalidated (e.g., closed) during the wait.
61
62**ZX_ERR_TIMED_OUT**  The specified deadline passed before any of the specified
63*signals* are observed on *handle*.
64
65**ZX_ERR_NOT_SUPPORTED**  *handle* is a handle that cannot be waited on
66(for example, a Port handle).
67
68## SEE ALSO
69
70[object_wait_async](object_wait_async.md),
71[object_wait_many](object_wait_many.md).
72