BLKS(2)                                                   BLKS(2)

     NAME
          blks - data blocks

     SYNOPSIS
          include "blks.m";
          blks := load Blks Blks->PATH;

          Blk: adt {
               data:     array of byte;
               rp:  int;
               wp:  int;

               read:     fn(b: self ref Blk, fd: ref Sys->FD, max: int): int;
               blen:     fn(b: self ref Blk): int;
               grow:     fn(b: self ref Blk, n: int);
               put: fn(b: self ref Blk, data: array of byte);
               get: fn(b: self ref Blk, cnt: int): array of byte;
               dump:     fn(b: self ref Blk);
          };

          init:     fn();
          utflen:   fn(s: string): int;
          pstring:  fn(a: array of byte, o: int, s: string): int;
          gstring:  fn(a: array of byte, o: int): (string, int);
          p16: fn(a: array of byte, o: int, v: int): int;
          g16: fn(f: array of byte, i: int): int;
          p32: fn(a: array of byte, o: int, v: int): int;
          g32: fn(f: array of byte, i: int): int;
          p64: fn(a: array of byte, o: int, v: big): int;
          g64: fn(f: array of byte, i: int): big;
          dtxt:     fn(s: string): string;

     DESCRIPTION
          Blks provides support for data buffering. The Blk data type
          a block of data. It is organized as a single array of bytes
          along with a read pointer Blks.rp, and a write pointer
          Blks.wp.  Available data is kept between rp and wp.  There
          may be room to add more data starting at wp.

          Init should be called before using the module.

          To create a new block, set all fields to null values.

          Blk.blen returns the number of bytes available for reading
          in the array.

          Blk.grow ensures that there are at least n bytes available
          for new data.  The block may grow more than requested and
          data may be moved to remove any leading hole in the buffer.

     BLKS(2)                                                   BLKS(2)

          Blk.put puts data in the block.  Blk.get returns cnt bytes
          from the block. The user is responsible to check out that
          there are enough bytes available before trying to get them.

          Blk.read can be used as a convenience to read data from a
          file descriptor into a block. At most max bytes are read.

          Remaining functions are helpers used to pack and unpack
          basic data types in a portable format.  Utflen is a conve-
          nience function that returns the number of bytes required to
          store a string in UTF-8.

          Pstring stores s at offset o in the array a and returns the
          offset past the string.  Gstring retrieves a string from a
          and returns both the string and the offset past the string.

          Functions P16, P32, and P64 put 16, 32, and 64 bits in lit-
          tle endian order into an array of bytes. They accept the
          offset o where to put the integer and return the offset past
          the integer.  G16, g32, and g64 are the counterparts, and
          unpack 16, 32, and 64 bits integers from an array of bytes
          at a given offset.  They return the integer unpacked.

          Dtxt returns a short version of s suitable for debug diag-
          nostics.

     SOURCE
          /usr/octopus/port/lib/blks.b