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 類型的元素數量。

bytes (以位元組為單位) 的長度會儲存在 actual_bytes 指向的位置。帳號代碼數量會儲存在 actual_handles 指向的位置。actual_bytes 或 actual_handles 有為 NULL，在這種情況下，系統會予以忽略。

管道訊息可能包含位元組資料和處理酬載，且只能讀取完整資料。無法進行部分讀取。

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 為非 NULL 和無效的指標，

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)。如果 options 已設定 ZX_CHANNEL_READ_MAY_DISCARD，則會捨棄訊息。

另請參閱