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 指定的通道。如果指针 handle 和 bytes 的值各自为零，则它们可以为 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 必须设置为零。

要么复制所有 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 由于内存不足而失败。 用户空间没有什么方法来处理此（不太可能）错误。在以后的 build 中，此错误不会再发生。

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 或 iovec 容量的总和超过 ZX_CHANNEL_MAX_MSG_BYTES 时，系统会生成 ZX_ERR_OUT_OF_RANGE。

备注

num_handles 是 handles 数组中元素数的计数，而不是其大小（以字节为单位）。

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

另请参阅