zx_socket_write

zx_socket_write

名称

socket_write —— 写入数据到socket

概要

#include <zircon/syscalls.h>
zx_status_t zx_socket_write(zx_handle_t handle, uint32_t options,
                            const void* buffer, size_t buffer_size,
                            size_t* actual) {

描述

socket_write() 尝试将buffer_size字节的数据写入handle指定的socket中。如果buffer_size为0，则指向bytes的指针可为NULL。

如果buffer_size为0，可将ZX_SOCKET_SHUTDOWN_READ和ZX_SOCKET_SHUTDOWN_WRITE 标志位的按位组合值传递给options以禁用从socket端点读取或写入： <!—

If ZX_SOCKET_SHUTDOWN_READ is passed to options, and buffer_size is 0, then reading is disabled for the socket endpoint at handle. All data buffered in the socket at the time of the call can be read, but further reads from this endpoint or writes to the other endpoint of the socket will fail with ZX_ERR_BAD_STATE. —>
- 如果将ZX_SOCKET_SHUTDOWN_READ标志位传递给options，并且buffer_size为0，则禁用在handle处的socket端点的数据读取。此时，还可以继续读取已在socket中缓冲的所有数据，但是未来从该端点读取或从相对端点写入都将失败并返回ZX_ERR_BAD_STATE错误码。 <!—
If ZX_SOCKET_SHUTDOWN_WRITE is passed to options, and buffer_size is 0, then writing is disabled for the socket endpoint at handle. Further writes to this endpoint or reads from the other endpoint of the socket will fail with ZX_ERR_BAD_STATE. —>
- 如果将ZX_SOCKET_SHUTDOWN_WRITE传递给options，并且buffer_size为0，则禁用在handle处的socket端点的数据写入。未来从此端点的写入或从相对端点读取都将失败并返回ZX_ERR_BAD_STATE错误码。

如果将ZX_SOCKET_CONTROL传递给options，则socket_write() 会尝试写入socket控制面。写入控制面的数据不能部分缺失，所以如果socket控制面没有足够的空间用于存放buffer，则它不会写入任何内容并返回ZX_ERR_OUT_OF_RANGE。

如果传入actual是NULL，那么它会被忽略。

如果socket没有足够的空间用于存放buffer中的所有数据，则ZX_SOCKET_STREAMsocket写入的数据可能会部分缺失。如果向socket写入非零数据量，则通过actual返回写入的数量，并且调用成功。否则，如果socket已满，则调用返回ZX_ERR_SHOULD_WAIT，并且客户端应该等待（例如，使用object_wait_one或 object_wait_async）。

ZX_SOCKET_DATAGRAM类型的socket写入不能部分缺失，所以如果socket没有足够的空间用于存放buffer，则它不会写入任何内容并返回ZX_ERR_SHOULD_WAIT。如果写入成功，则通过actual返回buffer_size。

权限

TODO(ZX-2399)

返回值

socket_write() 执行成功时返回ZX_OK。

错误码

ZX_ERR_BAD_HANDLE：handle是无效句柄。

ZX_ERR_BAD_STATE：options包含ZX_SOCKET_CONTROL标志位，但该socket不是由ZX_SOCKET_HAS_CONTROL创建的。

ZX_ERR_WRONG_TYPE：handle不是socket类型句柄。

ZX_ERR_INVALID_ARGS：下列情况之一：buffer是无效指针；options包含ZX_SOCKET_SHUTDOWN_READ和/或ZX_SOCKET_SHUTDOWN_WRITE标志位但buffer_size不为0；options不是0或ZX_SOCKET_SHUTDOWN_READ 和/或 ZX_SOCKET_SHUTDOWN_WRITE的组合。

ZX_ERR_ACCESS_DENIED：handle不具有ZX_RIGHT_WRITE权限。

ZX_ERR_SHOULD_WAIT: socket底层的缓冲区已满，或socket 是使用ZX_SOCKET_DATAGRAM标志位创建的并且buffer大于socket中的剩余空间。

ZX_ERR_BAD_STATE：已禁用通过此socket端点写入数据。

ZX_ERR_PEER_CLOSED：socket的相对端点已关闭。

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

另见

socket_create，socket_read。