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