1# zx_channel_read - zx_channel_read_etc 2 3## NAME 4 5channel_read - read a message from a channel 6 7## SYNOPSIS 8 9``` 10#include <zircon/syscalls.h> 11 12zx_status_t zx_channel_read(zx_handle_t handle, uint32_t options, 13 void* bytes, zx_handle_t* handles, 14 uint32_t num_bytes, uint32_t num_handles, 15 uint32_t* actual_bytes, uint32_t* actual_handles); 16 17 18zx_status_t zx_channel_read_etc(zx_handle_t handle, uint32_t options, 19 void* bytes, zx_handle_info_t* handles, 20 uint32_t num_bytes, uint32_t num_handles, 21 uint32_t* actual_bytes, uint32_t* actual_handles); 22``` 23 24## DESCRIPTION 25 26**channel_read**() and **channel_read_etc**() attempts to read the first 27message from the channel specified by *handle* into the provided *bytes* 28and/or *handles* buffers. 29 30The parameters *num_bytes* and *num_handles* are used to specify the 31size of the respective read buffers. 32 33Channel messages may contain both byte data and handle payloads and may 34only be read in their entirety. Partial reads are not possible. 35 36The *bytes* buffer is written before the *handles* buffer. In the event of 37overlap between these two buffers, the contents written to *handles* 38will overwrite the portion of *bytes* it overlaps. 39 40Both forms of read behave the same except that **channel_read**() returns an 41array of raw ``zx_handle_t`` handle values while **channel_read_etc**() returns 42an array of ``zx_handle_info_t`` structures of the form: 43 44``` 45typedef struct { 46 zx_handle_t handle; // handle value 47 zx_obj_type_t type; // type of object, see ZX_OBJ_TYPE_ 48 zx_rights_t rights; // handle rights 49 uint32_t unused; // set to zero 50} zx_handle_info_t; 51``` 52 53When communicating to an untrusted party over a channel, it is recommended 54that the **channel_read_etc**() form is used and each handle type and rights 55are validated against the expected values. 56 57## RIGHTS 58 59*handle* must have **ZX_RIGHT_READ**. 60 61## RETURN VALUE 62 63Both forms of read returns **ZX_OK** on success, if *actual_bytes* 64and *actual_handles* (if non-NULL), contain the exact number of bytes 65and count of handles read. 66 67## ERRORS 68 69**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle. 70 71**ZX_ERR_WRONG_TYPE** *handle* is not a channel handle. 72 73**ZX_ERR_INVALID_ARGS** If any of *bytes*, *handles*, *actual_bytes*, or 74*actual_handles* are non-NULL and an invalid pointer. 75 76**ZX_ERR_ACCESS_DENIED** *handle* does not have **ZX_RIGHT_READ**. 77 78**ZX_ERR_SHOULD_WAIT** The channel contained no messages to read. 79 80**ZX_ERR_PEER_CLOSED** The other side of the channel is closed. 81 82**ZX_ERR_NO_MEMORY** Failure due to lack of memory. 83There is no good way for userspace to handle this (unlikely) error. 84In a future build this error will no longer occur. 85 86**ZX_ERR_BUFFER_TOO_SMALL** The provided *bytes* or *handles* buffers 87are too small (in which case, the minimum sizes necessary to receive 88the message will be written to *actual_bytes* and *actual_handles*, 89provided they are non-NULL). If *options* has **ZX_CHANNEL_READ_MAY_DISCARD** 90set, then the message is discarded. 91 92## NOTES 93 94*num_handles* and *actual_handles* are counts of the number of elements 95in the *handles* array, not its size in bytes. 96 97## SEE ALSO 98 99[handle_close](handle_close.md), 100[handle_duplicate](handle_duplicate.md), 101[handle_replace](handle_replace.md), 102[object_wait_one](object_wait_one.md), 103[object_wait_many](object_wait_many.md), 104[channel_call](channel_call.md), 105[channel_create](channel_create.md), 106[channel_write](channel_write.md). 107