# zx_stream_create

## Summary

Create a stream from a VMO.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_stream_create(uint32_t options,
                                 zx_handle_t vmo,
                                 zx_off_t seek,
                                 zx_handle_t* out_stream);

## Description

`zx_stream_create()` creates a stream, which reads and writes the data in an
underlying VMO.

The seek offset for the stream is initialized to *seek*.

# Options

`ZX_STREAM_MODE_READ` The stream will be used for reading. If the given
*vmo* lacks `ZX_RIGHT_READ`, this function will return
`ZX_ERR_ACCESS_DENIED`. Otherwise, `ZX_RIGHT_READ` will be included as a
right on the created stream object.

`ZX_STREAM_MODE_WRITE` The stream will be used for writing. If the given
*vmo* lacks `ZX_RIGHT_WRITE`, this function will return
`ZX_ERR_ACCESS_DENIED`. Otherwise, `ZX_RIGHT_WRITE` will be included as a
right on the created stream object.

`ZX_STREAM_MODE_APPEND` The stream is created in append mode. A stream in
append mode will atomically set the seek offset of the stream to the content
size of the stream prior to writing data in `zx_stream_writev()`.

## Rights

TODO(https://fxbug.dev/42107318)

## Return value

`zx_stream_create()` returns `ZX_OK` on success. In the event of
failure, one of the following values is returned.

## Errors

`ZX_ERR_BAD_HANDLE` *vmo* is not a valid handle.

`ZX_ERR_WRONG_TYPE` *vmo* is contiguous, physical or not a VMO handle.

`ZX_ERR_ACCESS_DENIED` *vmo* does not have the rights required for the given
options.

`ZX_ERR_INVALID_ARGS` *out_stream* is an invalid pointer or NULL, *options*
has an unsupported bit set to 1.

`ZX_ERR_NO_MEMORY` Failure due to lack of memory.

## See also

- [`zx_stream_readv()`](https://fuchsia.dev/reference/syscalls/stream_readv)
- [`zx_stream_readv_at()`](https://fuchsia.dev/reference/syscalls/stream_readv_at)
- [`zx_stream_seek()`](https://fuchsia.dev/reference/syscalls/stream_seek)
- [`zx_stream_writev()`](https://fuchsia.dev/reference/syscalls/stream_writev)
- [`zx_stream_writev_at()`](https://fuchsia.dev/reference/syscalls/stream_writev_at)