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