1# zx_object_wait_many
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7object_wait_many - wait for signals on multiple objects
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_many(zx_wait_item_t* items,
17                                size_t count,
18                                zx_time_t deadline);
19```
20
21## DESCRIPTION
22
23`zx_object_wait_many()` is a blocking syscall which causes the caller to
24wait until either the *deadline* passes or at least one of the specified
25signals is asserted by the object to which the associated handle refers.
26If an object is already asserting at least one of the specified signals,
27the wait ends immediately.
28
29```
30typedef struct {
31    zx_handle_t handle;
32    zx_signals_t waitfor;
33    zx_signals_t pending;
34} zx_wait_item_t;
35```
36
37The caller must provide *count* `zx_wait_item_t`s in the *items* array,
38containing the handle and signals bitmask to wait for for each item.
39
40The *deadline* parameter specifies a deadline with respect to
41**ZX_CLOCK_MONOTONIC**.  **ZX_TIME_INFINITE** is a special value meaning wait
42forever.
43
44Upon return, the *pending* field of *items* is filled with bitmaps indicating
45which signals are pending for each item.
46
47The *pending* signals in *items* may not reflect the actual state of the object's
48signals if the state of the object was modified by another thread or
49process.  (For example, a Channel ceases asserting **ZX_CHANNEL_READABLE**
50once the last message in its queue is read).
51
52The maximum number of items that may be waited upon is **ZX_WAIT_MANY_MAX_ITEMS**,
53which is 8.  To wait on more things at once use [Ports](../objects/port.md).
54
55## RIGHTS
56
57<!-- Updated by update-docs-from-abigen, do not edit. -->
58
59Every entry of *items* must have a *handle* field with **ZX_RIGHT_TRANSFER**.
60
61## RETURN VALUE
62
63`zx_object_wait_many()` returns **ZX_OK** if any of *waitfor* signals were
64observed on their respective object before *deadline* passed.
65
66In the event of **ZX_ERR_TIMED_OUT**, *items* may reflect state changes
67that occurred after the deadline passed, but before the syscall returned.
68
69In the event of **ZX_ERR_CANCELED**, one or more of the items being waited
70upon have had their handles closed, and the *pending* field for those items
71will have the **ZX_SIGNAL_HANDLE_CLOSED** bit set.
72
73For any other return value, the *pending* fields of *items* are undefined.
74
75## ERRORS
76
77**ZX_ERR_INVALID_ARGS**  *items* isn't a valid pointer.
78
79**ZX_ERR_OUT_OF_RANGE**  *count* is greater than **ZX_WAIT_MANY_MAX_ITEMS**.
80
81**ZX_ERR_BAD_HANDLE**  one of *items* contains an invalid handle.
82
83**ZX_ERR_ACCESS_DENIED**  One or more of the provided *handles* does not
84have **ZX_RIGHT_WAIT** and may not be waited upon.
85
86**ZX_ERR_CANCELED**  One or more of the provided *handles* was invalidated
87(e.g., closed) during the wait.
88
89**ZX_ERR_TIMED_OUT**  The specified deadline passed before any of the specified signals are
90observed on any of the specified handles.
91
92**ZX_ERR_NOT_SUPPORTED**  One of the *items* contains a handle that cannot
93be waited one (for example, a Port handle).
94
95**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
96There is no good way for userspace to handle this (unlikely) error.
97In a future build this error will no longer occur.
98
99## BUGS
100
101*pending* more properly should be called *observed*.
102
103## SEE ALSO
104
105 - [`zx_object_wait_async()`]
106 - [`zx_object_wait_one()`]
107
108<!-- References updated by update-docs-from-abigen, do not edit. -->
109
110[`zx_object_wait_async()`]: object_wait_async.md
111[`zx_object_wait_one()`]: object_wait_one.md
112