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 A file descriptor backed STREAM gains a buffer of the given size
  16 prefixed by a 32 byte STREAM header of the following layout:
  17
  18 ====
  19 .file descriptor stream
  20 [caption='Layout {counter:layout}: ']
  21 ----
  22   8 bytes = size of buffer (excluding the 32 byte header)
  23   8 bytes source file descriptor
  24   8 bytes current fill
  25   8 current read position
  26 ----
  27 ====
  28
  29 ==== Memory block backed STREAM
  30
  31 A memory block stream is only the header (though allocated via
  32 <<p_malloc,MALLOC>> which reserves a full kernel page) with the
  33 following layout:
  34
  35 ====
  36 .memory block stream
  37 [caption='Layout {counter:layout}: ']
  38 ----
  39   8 bytes = block address
  40   8 -1 (indicates memory block)
  41   8 size of block (taken from the block's first 8 bytes)
  42   8 current read position
  43 ----
  44 ====
  45