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 个句柄 handle。如果指针 handles 和 bytes 的 分别为 0。

成功后，handles 数组中所有 num_handles 个句柄 会附加在邮件中，并可供读者查看 从通道的另一端发送该消息。

所有标识名都会被舍弃，并且无法再供调用方在 成功或失败如果需要标识名，请使用 zx_channel_write_etc() 以供发件人保留

包含 handle（正在写入的频道的句柄）无效 to) 包含在 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 具有 capacity 总和的 bytes 数组的 zx_channel_iovec_t 个元素 所有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。

每个 handles 条目都必须具有 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_ERR_OUT_OF_RANGE ZX_CHANNEL_MAX_MSG_IOVEC 或 iovec 容量的总和超过 ZX_CHANNEL_MAX_MSG_BYTES。

备注

num_handles 是 handles 中元素数量的计数 而不是以字节为单位的大小。

消息的字节大小限制尚未最终确定。

另请参阅