zx_channel_write_etc

摘要

撰寫一則訊息給某個管道。

宣告

#include <zircon/syscalls.h>

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

說明

就像 zx_channel_write() 一樣，它會嘗試寫入 num_bytes 的訊息 位元組和 num_handles 會處理 handle 指定的管道，但 它就會對執行中的 透過 控點，也就是 zx_handle_disposition_t 陣列進行轉移：

typedef struct zx_handle_disposition {
    zx_handle_op_t operation;
    zx_handle_t handle;
    zx_obj_type_t type;
    zx_rights_t rights;
    zx_status_t result;
} zx_handle_disposition_t;

在 zx_handle_disposition_t 中，handle 是要操作的來源控制代碼， rights 是您要的最終權利 (而非遮罩)，且必須設定 result 至 ZX_OK。所有來源帳號代碼都必須有 ZX_RIGHT_TRANSFER，但 你可以在權利中移除該訊息，這樣一來，訊息中就不會提供該訊息 接收器。

type 的用途是驗證呼叫端的物件類型 預期為 handle 。如要略過驗證，請按 ZX_OBJ_TYPE_NONE 檢查或其中一個 zx_obj_type_t 定義的類型。

套用至 handle 的作業為下列任一項目：

帳號代碼將會移轉具有能力 right，也就是 ZX_RIGHT_SAME_RIGHTS 或縮減權利組合，或ZX_RIGHT_NONE另外，這項作業 權利中的 ZX_RIGHT_TRANSFER，表示接收器無法使用能力。

如果有任何作業失敗，該來源控制代碼的錯誤代碼會寫入 result，且 第一次失敗時會傳回 zx_channel_write_etc() 的傳回值。所有語言 系統會嘗試執行 handles 陣列中的作業，即使一或多項作業失敗也一樣。

每個項目的所有作業都必須成功，才能寫入訊息。成功時，控制代碼 全部附加在郵件上，並成為「 和整個管道的相對關係

如果在 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_etc() 會在成功時傳回 ZX_OK。

錯誤

ZX_ERR_BAD_HANDLE 帳號代碼不是有效的帳號代碼， handles 不是有效的帳號代碼，或是有重複的帳號代碼 如果沒有 ZX_HANDLE_OP_DUPLICATE 旗標，則在 handles 陣列中。

ZX_ERR_WRONG_TYPE 帳號代碼不是管道帳號代碼或任何來源帳號代碼 在 handles 中，與物件類型 type 不符。

ZX_ERR_INVALID_ARGS bytes 是無效的指標，處理常式 是無效的指標，或 options 不是零，或 operation 不是 必須是 ZX_HANDLE_OP_MOVE 或 ZX_HANDLE_OP_DUPLICATE 之一，或任何來源 handles[i]->handle 的帳號代碼並未指定 whandle[i]->rights 上。 如果已指定 ZX_CHANNEL_WRITE_USE_IOVEC 選項， ZX_ERR_INVALID_ARGS如果緩衝區欄位含有 指標無效，或是保留欄位不是零。

handles 陣列包含 ZX_ERR_NOT_SUPPORTED 帳號代碼。

ZX_ERR_ACCESS_DENIED 帳號代碼沒有 ZX_RIGHT_WRITE 或 帳號代碼中的任何來源控制代碼都沒有 ZX_RIGHT_TRANSFER；或 在發生以下情況時，帳號代碼中的任何來源控制代碼沒有 ZX_RIGHT_DUPLICATE 已指定 ZX_HANDLE_OP_DUPLICATE 作業。

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。

附註

如果呼叫端移除附加於控制代碼的 ZX_RIGHT_TRANSFER 訊息讀取者收到的控點，無法 寫入其他管道，但還是能根據 且可視需要關閉

另請參閱