adoc/p_stream.adoc

   1 // stdio.asm:   WORD p_stream,'STREAM',fasm
   2
   3 anchor:p_stream[]
   4
   5 === Word: STREAM
   6 ....
   7 Data stack: ( fd size -- addr ) or ( block -1 -- addr )
   8 ....
   9
  10 "STREAM" is a function word that sets up a buffer for an input file
  11 descriptor or for a memory block (of size+data).
  12
  13 ==== File descriptor backed STREAM
  14
  15
  16 A file descriptor backed STREAM gains a buffer of the given size
  17 prefixed by a 32 byte STREAM header of the following layout:
  18
  19 ====
  20 .file descriptor stream
  21 [caption='Layout {counter:layout}: ']
  22 ----
  23   8 bytes = size of buffer (excluding the 32 byte header)
  24   8 bytes source file descriptor
  25   8 bytes current fill
  26   8 current read position
  27 ----
  28 ====
  29
  30 ==== Memory block backed STREAM
  31
  32 A memory block stream is only the header (though allocated via
  33 <<p_malloc,MALLOC>> which reserves a full kernel page) with the
  34 following layout:
  35
  36 ====
  37 .memory block stream
  38 [caption='Layout {counter:layout}: ']
  39 ----
  40   8 bytes = block address
  41   8 -1 (indicates memory block)
  42   8 size of block (taken from the block's first 8 bytes)
  43   8 current read position
  44 ----
  45 ====
  46