1# zx_channel_read_etc
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7channel_read_etc - read a message from a channel
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_channel_read_etc(zx_handle_t handle,
17                                uint32_t options,
18                                void* bytes,
19                                zx_handle_info_t* handles,
20                                uint32_t num_bytes,
21                                uint32_t num_handles,
22                                uint32_t* actual_bytes,
23                                uint32_t* actual_handles);
24```
25
26## DESCRIPTION
27
28See [`zx_channel_read()`] for a full description.
29
30Both forms of read behave the same except that [`zx_channel_read()`] returns an
31array of raw `zx_handle_t` handle values while `zx_channel_read_etc()` returns
32an array of `zx_handle_info_t` structures of the form:
33
34```
35typedef struct {
36    zx_handle_t handle;     // handle value
37    zx_obj_type_t type;     // type of object, see ZX_OBJ_TYPE_
38    zx_rights_t rights;     // handle rights
39    uint32_t unused;        // set to zero
40} zx_handle_info_t;
41```
42
43When communicating to an untrusted party over a channel, it is recommended
44that the `zx_channel_read_etc()` form is used and each handle type and rights
45are validated against the expected values.
46
47## RIGHTS
48
49<!-- Updated by update-docs-from-abigen, do not edit. -->
50
51*handle* must be of type **ZX_OBJ_TYPE_CHANNEL** and have **ZX_RIGHT_READ**.
52
53## RETURN VALUE
54
55Both forms of read returns **ZX_OK** on success, if *actual_bytes*
56and *actual_handles* (if non-NULL), contain the exact number of bytes
57and count of handles read.
58
59## ERRORS
60
61**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
62
63**ZX_ERR_WRONG_TYPE**  *handle* is not a channel handle.
64
65**ZX_ERR_INVALID_ARGS**  If any of *bytes*, *handles*, *actual_bytes*, or
66*actual_handles* are non-NULL and an invalid pointer.
67
68**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_READ**.
69
70**ZX_ERR_SHOULD_WAIT**  The channel contained no messages to read.
71
72**ZX_ERR_PEER_CLOSED**  The other side of the channel is closed.
73
74**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
75There is no good way for userspace to handle this (unlikely) error.
76In a future build this error will no longer occur.
77
78**ZX_ERR_BUFFER_TOO_SMALL**  The provided *bytes* or *handles* buffers
79are too small (in which case, the minimum sizes necessary to receive
80the message will be written to *actual_bytes* and *actual_handles*,
81provided they are non-NULL). If *options* has **ZX_CHANNEL_READ_MAY_DISCARD**
82set, then the message is discarded.
83
84## NOTES
85
86*num_handles* and *actual_handles* are counts of the number of elements
87in the *handles* array, not its size in bytes.
88
89## SEE ALSO
90
91 - [`zx_channel_call()`]
92 - [`zx_channel_create()`]
93 - [`zx_channel_read()`]
94 - [`zx_channel_write()`]
95 - [`zx_handle_close()`]
96 - [`zx_handle_duplicate()`]
97 - [`zx_handle_replace()`]
98 - [`zx_object_wait_async()`]
99 - [`zx_object_wait_many()`]
100 - [`zx_object_wait_one()`]
101
102<!-- References updated by update-docs-from-abigen, do not edit. -->
103
104[`zx_channel_call()`]: channel_call.md
105[`zx_channel_create()`]: channel_create.md
106[`zx_channel_read()`]: channel_read.md
107[`zx_channel_write()`]: channel_write.md
108[`zx_handle_close()`]: handle_close.md
109[`zx_handle_duplicate()`]: handle_duplicate.md
110[`zx_handle_replace()`]: handle_replace.md
111[`zx_object_wait_async()`]: object_wait_async.md
112[`zx_object_wait_many()`]: object_wait_many.md
113[`zx_object_wait_one()`]: object_wait_one.md
114