devstream: fast sequential file access with 9p pipelining experiment

1 files changed, 40 insertions, 0 deletions

diff --git a/sys/man/3/stream b/sys/man/3/stream
new file mode 100644
index 000000000..fb20cb51f
--- /dev/null
+++ b/sys/man/3/stream
@@ -0,0 +1,40 @@
+.TH STREAM 3 
+.SH NAME
+stream \- fast sequential file access
+.SH SYNOPSIS
+.nf
+.B bind #¶ /fd
+
+.B /fd/0stream
+.B /fd/1stream
+\&...
+.fi
+.SH DESCRIPTION
+The
+.I stream
+device serves a one-level directory containing files of the form
+.IR N stream
+where
+.I N
+is a file descriptor of the current process.
+.PP
+An
+.IR open (2)
+returns a stream file descriptor connected to the original file
+refered to by the file descriptor
+.IR N .
+When a stream was opend for reading, the device will start
+continuously reading the file in the background until it reaches
+the end of the file. A
+.IR read (2)
+on the stream consumes the prefetched data in sequential order.
+.PP
+When a stream is opend for writing, writes to the stream will
+return immidiately without waiting for the data to be written
+to the file. A zero-length write can be used to wait for the
+buffered data to drain and return any previous write errors.
+.SH SEE ALSO
+.IR dup (2),
+.IR pipe (3)
+.SH SOURCE
+.B /sys/src/9/port/devstream.c