zx_channel_write

摘要

撰寫訊息給管道。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_channel_write(zx_handle_t handle,
                             uint32_t options,
                             const void* bytes,
                             uint32_t num_bytes,
                             const zx_handle_t* handles,
                             uint32_t num_handles);

說明

zx_channel_write() 會嘗試將 num_bytes 位元組數和 num_handles 控點的訊息寫入處理常式指定的管道。如果指標「處理」和「位元組」各自為零，則指標可能為 NULL。

成功時，handles 陣列中的所有 num_handles 控點都會附加至訊息，並從管道的另一端提供給該訊息的讀者。

不論成功或失敗，所有帳號代碼都會遭到捨棄，且呼叫端無法再使用。如果寄件者需要保留帳號代碼，請使用 zx_channel_write_etc()。

在 handles 陣列 (訊息中傳送的控點) 中加入 handle (寫入目標管道的控制代碼) 是無效做法。

可在訊息中傳送的帳號代碼數量上限為 ZX_CHANNEL_MAX_MSG_HANDLES，也就是 64。

可在訊息中傳送的位元組數量上限為 ZX_CHANNEL_MAX_MSG_BYTES，也就是 65536。

zx_channel_read() 或 zx_channel_read_etc() 會清空訊息。 如未及時清空訊息，可能會導致使用過多核心記憶體，進而產生例外狀況。詳情請參閱 ipc 限制。

ZX_CHANNEL_WRITE_USE_IOVEC 選項

如果指定 ZX_CHANNEL_WRITE_USE_IOVEC 選項，系統會將 bytes 解讀為 zx_channel_iovec_t 陣列，並指定要依序複製到訊息的位元組切片。num_bytes 會指定 bytes 中的 zx_channel_iovec_t 陣列元素數量。

typedef struct zx_channel_iovec {
  const void* buffer;      // User-space bytes.
  uint32_t capacity;       // Number of bytes.
  uint32_t reserved;       // Reserved.
} zx_channel_iovec_t;

bytes 陣列最多只能有 ZX_CHANNEL_MAX_MSG_IOVEC 或 8192 zx_channel_iovec_t 個元素，且所有 zx_channel_iovec_t 的總和為 capacity，且不超過 ZX_CHANNEL_MAX_MSG_BYTES 或 65536 位元組。buffer 不必對齊，而如果 capacity 為零，則只能設為 NULL。reserved 必須設為 0。

系統只會複製所有 zx_channel_iovec_t 並傳送訊息，或是不會複製訊息，因此不會傳送訊息。使用傳送帳號代碼的方式維持不變。

權限

handle 必須是 ZX_OBJ_TYPE_CHANNEL 類型，且具有 ZX_RIGHT_WRITE。

每個帳號代碼的項目都必須包含 ZX_RIGHT_TRANSFER。

傳回值

zx_channel_write() 會在成功時傳回 ZX_OK。

錯誤

ZX_ERR_BAD_HANDLE handle 不是有效的控制代碼，handles 中的任何元素都不是有效的控制代碼，或者 handles 陣列中的控點有重複的控點。

ZX_ERR_WRONG_TYPE handle 不是管道帳號代碼。

ZX_ERR_INVALID_ARGS bytes 是無效指標，handles 是無效指標，或 options 包含無效的選項位元。如果指定 ZX_CHANNEL_WRITE_USE_IOVEC 選項，當 buffer 欄位包含無效指標，或保留欄位不是零，就會產生 ZX_ERR_INVALID_ARGS。

在 handles 陣列中找到 ZX_ERR_NOT_SUPPORTED handle。執行寫入作業的管道控制代碼不可納入 handles 陣列中。換句話說，無法將管道帳號代碼寫入其所屬的管道。 如要修正錯誤，請確認 handle 不在 handles 陣列中。

ZX_ERR_ACCESS_DENIED handle 沒有 ZX_RIGHT_WRITE，或 handles 中的任何元素都沒有 ZX_RIGHT_TRANSFER。

ZX_ERR_PEER_CLOSED 管道另一側已關閉。

ZX_ERR_NO_MEMORY 因記憶體不足而失敗。使用者空間無法以任何方式處理這個錯誤 (極可能) 錯誤。日後的建構作業不會再發生這個錯誤。

ZX_ERR_OUT_OF_RANGE num_bytes 或 num_handles 分別大於 ZX_CHANNEL_MAX_MSG_BYTES 或 ZX_CHANNEL_MAX_MSG_HANDLES。如果指定 ZX_CHANNEL_WRITE_USE_IOVEC 選項，當 num_bytes 大於 ZX_CHANNEL_MAX_MSG_IOVEC 或生物容量總和超過 ZX_CHANNEL_MAX_MSG_BYTES 時，就會產生 ZX_ERR_OUT_OF_RANGE。

附註

num_handles 是「處理常式」陣列中的元素數量，而非以位元組為單位的大小。

訊息的位元組大小限制尚未定案。

另請參閱