# Stream

## NAME

stream - A readable, writable, seekable interface to some underlying storage

## SYNOPSIS

A stream is an interface for reading and writing data to some underlying
storage, typically a VMO.

## DESCRIPTION

A stream maintains a reference to some underlying storage, typically a VMO,
as well as a seek offset, which is used to position read and write operations.

Unlike the read and write operations on a VMO, the read and write operations
on a stream can be short, which the operations can complete successfully
without filling (or, respectively, emptying) the supplied buffers. For example,
a read that extends beyond the end of a VMO will simply fail whereas a read
that extends beyond the end of a stream will succeed in reading to the end of
the stream and partially filling the buffer.

Writes that extend beyond the end of the underlying storage attempt to increase
the size of the underlying storage rather than failing immediately. For
example, a write to a stream that extends beyond the end of the underlying VMO
will attempt to resize the VMO rather than failing. If the resize operation
fails on the underlying VMO, the write can end up being short.

## SYSCALLS

 - [`zx_stream_create()`] - create a stream from a VMO
 - [`zx_stream_readv()`] - read data from the stream at the current seek offset
 - [`zx_stream_readv_at()`] - read data from the stream at a given offset
 - [`zx_stream_writev()`] - write data to the stream at the current seek offset
 - [`zx_stream_writev_at()`] - write data to the stream at a given offset
 - [`zx_stream_seek()`] - modify the current seek offset of the stream

[`zx_stream_create()`]: /reference/syscalls/stream_create.md
[`zx_stream_readv()`]: /reference/syscalls/stream_readv.md
[`zx_stream_readv_at()`]: /reference/syscalls/stream_readv_at.md
[`zx_stream_writev()`]: /reference/syscalls/stream_writev.md
[`zx_stream_writev_at()`]: /reference/syscalls/stream_writev_at.md
[`zx_stream_seek()`]: /reference/syscalls/stream_seek.md