zx_stream_writev

Summary

Write data to a stream at the current seek offset.

Declaration

#include <zircon/syscalls.h>

zx_status_t zx_stream_writev(zx_handle_t handle,
                             uint32_t options,
                             const zx_iovec_t* vectors,
                             size_t num_vectors,
                             size_t* actual);

Description

zx_stream_writev() attempts to write bytes to the stream, starting at the current seek offset, from the buffers specified by vectors and num_vectors. If successful, the number of bytes actually written are return via actual.

If options contains ZX_STREAM_APPEND or the stream is in append mode, the seek offset of the stream is atomically set to the content size of the stream prior to writing the data.

If the write operation would write beyond the end of the stream, the function will attempt to increase the content size of the stream in order to receive the given data, filling any new, unwritten content with zero bytes.

The content size of the stream is bound by the size of the underlying VMO. If the size of the VMO is insufficient to receive the entire given data, the operation is considered a partial write. If no bytes are written, the operation will return ZX_ERR_FILE_BIG, ZX_ERR_OUT_OF_RANGE or ZX_ERR_NO_SPACE, as appropriate. Otherwise during a partial write, ZX_OK will be returned and actual will be less than the sum of the capacities of the buffers.

If a NULL actual is passed in, it will be ignored.

Advances the seek offset of the stream by the actual number of bytes written. If the write fails, the seek offset could either remain the same or have been changed to an unspecified value.

If the contents of vectors change during this operation, if any of the buffers overlap, or if any of the buffers overlap vectors, the behavior is unspecified.

Rights

handle must be of type ZX_OBJ_TYPE_STREAM and have ZX_RIGHT_WRITE.

Return value

zx_stream_writev() returns ZX_OK on success, and writes into actual (if non-NULL) the exact number of bytes written.

Errors

ZX_ERR_BAD_HANDLE handle is not a valid handle.

ZX_ERR_WRONG_TYPE handle is not a stream handle.

ZX_ERR_ACCESS_DENIED handle does not have the ZX_RIGHT_WRITE right.

ZX_ERR_INVALID_ARGS vectors is an invalid zx_iovec_t or options has an unsupported bit set to 1.

ZX_ERR_NOT_FOUND the vectors address, or an address specified within vectors does not map to address in address space.

ZX_ERR_BAD_STATE the underlying data source cannot be written.

ZX_ERR_FILE_BIG the stream has exceeded a predefined maximum size limit.

ZX_ERR_NO_SPACE the underlying storage medium does not have sufficient space.

ZX_ERR_OUT_OF_RANGE attempt to write to a position that cannot be accommodated by the underlying VMO.

See also