// stdio.asm:	WORD p_stream,'STREAM',fasm

anchor:p_stream[]

=== Word: STREAM
....
Data stack: ( fd size -- addr ) or ( block -1 -- addr )
....

"STREAM" is a function word that sets up a buffer for an input file
descriptor or for a memory block (of size+data).

==== File descriptor backed STREAM


A file descriptor backed STREAM gains a buffer of the given size
prefixed by a 32 byte STREAM header of the following layout:

====
.file descriptor stream
[caption='Layout {counter:layout}: ']
----
  8 bytes = size of buffer (excluding the 32 byte header)
  8 bytes source file descriptor
  8 bytes current fill
  8 current read position
----
====

==== Memory block backed STREAM

A memory block stream is only the header (though allocated via
<<p_malloc,MALLOC>> which reserves a full kernel page) with the
following layout:

====
.memory block stream
[caption='Layout {counter:layout}: ']
----
  8 bytes = block address
  8 -1 (indicates memory block)
  8 size of block (taken from the block's first 8 bytes)
  8 current read position
----
====