zx_channel_read

摘要

閱讀特定管道的訊息。

宣告

#include <zircon/syscalls.h>

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

說明

zx_channel_read() 會嘗試讀取管道的第一則訊息 由「處理常式」指定至提供的位元組和/或處理常式緩衝區。

num_bytes 和 num_handles 和 以及各自的讀取緩衝區num_bytes 是位元組數量， num_handles 是 zx_handle_t 類型的元素數量。

位元組的長度 (以位元組為單位) 會儲存在指向 actual_bytes。帳號代碼會儲存在 actual_handles。actual_bytes 或 actual_bytes 可以是空值， 在這類情況下，系統會忽略這些參數

管道訊息可能包含位元組資料及處理酬載，且 但不得讀取完整內容無法局部讀取。

位元組緩衝區會在 handles 緩衝區之前寫入。如果發生以下情況： 在兩個緩衝區之間重疊，也就是寫入處理常式的內容 會覆寫重疊的位元組部分。

如要透過管道與不受信任的對象溝通，則建議採取以下做法： 系統會使用 zx_channel_read_etc() 表單以及每種帳號代碼類型 並根據預期值來驗證權利。

權限

handle 必須是 ZX_OBJ_TYPE_CHANNEL 類型，且包含 ZX_RIGHT_READ。

傳回值

成功時會傳回 ZX_OK。如果為非 NULL，代表 actual_bytes 和 actual_handles 含有確切的位元組數和數量 控制代碼讀取。

錯誤

ZX_ERR_BAD_HANDLE 帳號代碼不是有效的帳號代碼。

ZX_ERR_WRONG_TYPE 帳號代碼不是管道帳號代碼。

ZX_ERR_INVALID_ARGS 表示任何 bytes、handles、actual_bytes 或 actual_handles 是非空值且無效的指標。

ZX_ERR_ACCESS_DENIED 帳號代碼沒有 ZX_RIGHT_READ。

ZX_ERR_SHOULD_WAIT 頻道不含任何可閱讀的訊息 即可開啟管道

ZX_ERR_PEER_CLOSED 頻道不含任何可閱讀的訊息 就會關閉管道

ZX_ERR_NO_MEMORY 因記憶體不足而失敗。 使用者空間無法妥善處理這種 (異常) 錯誤。 在日後的版本中不會再發生這個錯誤。

ZX_ERR_BUFFER_TOO_SMALL 提供的位元組或處理常式緩衝區 太小 (在這種情況下，需接收的 這樣訊息就會寫入 actual_bytes 和 actual_handles， (前提是空值並非空值)。如果選項包含ZX_CHANNEL_READ_MAY_DISCARD 便會遭到捨棄。

另請參閱