zx_channel_write

英文原文快照

名称

channel_write —— 向channel写入消息

概要

  1. #include <zircon/syscalls.h>
  3. zx_status_t zx_channel_write(zx_handle_t handle, uint32_t options,
  4.                              void* bytes, uint32_t num_bytes,
  5.                              zx_handle_t* handles, uint32_t num_handles);

描述

channel_write() 尝试将num_bytes个字节和num_handles个句柄的消息写入handle指定的channel中。如果它们各自的大小为零，则handles和bytes指针可以是NULL。

执行成功时，调用者进程不再可以访问handles数组中所有num_handles个句柄——它们已加入到可以从channel的另一端读取的消息中。在任何失败发生时，所有句柄都将被丢弃而不是被传输。

在（在消息中发送的句柄）handles数组中包含（正在写入通道的句柄本身）handle是无效的。

可在消息中发送的最大句柄数是ZX_CHANNEL_MAX_MSG_HANDLES，即64。

可在消息中发送的最大字节数是ZX_CHANNEL_MAX_MSG_BYTES，即65536。

权限

handle必须具有ZX_RIGHT_WRITE权限。

handles中的每个句柄必须具有ZX_RIGHT_TRANSFER权限。

返回值

channel_write() 调用成功则返回ZX_OK。

错误码

ZX_ERR_BAD_HANDLE：handle是无效句柄，handles中存在无效句柄，或handles数组中的句柄存在重复项。

ZX_ERR_WRONG_TYPE：handle是无效句柄。

ZX_ERR_INVALID_ARGS：提供的指针存在无效的或为null的，或num_bytes小于4，或者options为非零。

ZX_ERR_NOT_SUPPORTED: handle在handles数组中被找到，或者说handles中的一个句柄是（正在被写入的通道句柄的）handle本身。

ZX_ERR_ACCESS_DENIED：handle没有ZX_RIGHT_WRITE权限，或handles中的存在没有ZX_RIGHT_TRANSFER权限的元素。

ZX_ERR_PEER_CLOSED：channel的另一侧已关闭。

ZX_ERR_NO_MEMORY：由于内存不足导致的失败。而用户空间无法处理这个（不太可能发生的）错误。在将来的构建版本中，将不再出现此错误。

ZX_ERR_OUT_OF_RANGE： num_bytes或num_handles大于channel最大允许的消息大小。

注释

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

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

另见

handle_close，handle_duplicate，handle_replace，object_wait_one，object_wait_many，channel_call，channel_create，channel_read。