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 會控制由 處理常式。如果指標處理常式和 bytes 可能是 NULL， 個別大小為 0

成功時，handles 陣列中的所有控點 num_handles 即成功。 附加至郵件，並可供讀者存取 則發送訊息

所有帳號代碼都會遭到捨棄，來電者無法再使用。 順利完成或失敗如果需要帳號代碼，請使用 zx_channel_write_etc() 以便由傳送者保留。

未包含帳號代碼 (編寫的管道帳號代碼) 無效 ) 加入 handles 陣列 (訊息中傳送的控制代碼)。

訊息中可傳送的帳號代碼數量上限為 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;

最多只能有 ZX_CHANNEL_MAX_MSG_IOVEC 或 8192 bytes 陣列的 zx_channel_iovec_t 元素和 capacity 的總和 所有zx_channel_iovec_t (不超過 ZX_CHANNEL_MAX_MSG_BYTES) 65536 位元組。buffer 不需要對齊，只有在符合以下條件時，才是 NULL capacity 為零。「reserved」必須設為零。

系統會複製所有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 選項， ZX_ERR_INVALID_ARGS如果 buffer 欄位含有 指標無效，或是保留欄位不是零。

在 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_ERR_OUT_OF_RANGE」 ZX_CHANNEL_MAX_MSG_IOVEC 或碘容量總和超過 ZX_CHANNEL_MAX_MSG_BYTES。

附註

num_handles 是 帳號代碼中的元素數量計數 而非其大小 (以位元組為單位)。

此時訊息的位元組大小限制尚未完成。

另請參閱