zx_channel_read_etc

Summary

Read a message from a channel.

Declaration

#include <zircon/syscalls.h>

zx_status_t zx_channel_read_etc(zx_handle_t handle,
                                uint32_t options,
                                void* bytes,
                                zx_handle_info_t* handles,
                                uint32_t num_bytes,
                                uint32_t num_handles,
                                uint32_t* actual_bytes,
                                uint32_t* actual_handles);

Description

See zx_channel_read() for a full description.

Both forms of read behave the same except that zx_channel_read() returns an array of raw zx_handle_t handle values while zx_channel_read_etc() returns an array of zx_handle_info_t structures of the form:

typedef struct {
    zx_handle_t handle;     // handle value
    zx_obj_type_t type;     // type of object, see ZX_OBJ_TYPE_
    zx_rights_t rights;     // handle rights
    uint32_t unused;        // set to zero
} zx_handle_info_t;

When communicating to an untrusted party over a channel, it is recommended that the zx_channel_read_etc() form is used and each handle type and rights are validated against the expected values.

Rights

handle must be of type ZX_OBJ_TYPE_CHANNEL and have ZX_RIGHT_READ.

Return value

Both forms of read return ZX_OK on success, if actual_bytes and actual_handles (if non-NULL), contain the exact number of bytes and count of handles read.

Errors

ZX_ERR_BAD_HANDLE handle is not a valid handle.

ZX_ERR_WRONG_TYPE handle is not a channel handle.

ZX_ERR_INVALID_ARGS If any of bytes, handles, actual_bytes, or actual_handles are non-NULL and an invalid pointer.

ZX_ERR_ACCESS_DENIED handle does not have ZX_RIGHT_READ.

ZX_ERR_SHOULD_WAIT The channel contained no messages to read and the other side of the channel is open.

ZX_ERR_PEER_CLOSED The channel contained no messages to read and the other side of the channel is closed.

ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.

ZX_ERR_BUFFER_TOO_SMALL The provided bytes or handles buffers are too small (in which case, the minimum sizes necessary to receive the message will be written to actual_bytes and actual_handles, provided they are non-NULL). If options has ZX_CHANNEL_READ_MAY_DISCARD set, then the message is discarded.

Notes

num_handles and actual_handles are counts of the number of elements in the handles array, not its size in bytes.