BIN(2)                                                     BIN(2)

     NAME
          binalloc, bingrow, binfree - grouped memory allocation

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <bin.h>

          typedef struct Bin  Bin;

          void  *binalloc(Bin **bp, ulong size, int clr);

          void  *bingrow(Bin **bp, void *op, ulong osize,
                ulong size, int clr);

          void  binfree(Bin **bp);

     DESCRIPTION
          These routines provide simple grouped memory allocation and
          deallocation.  Items allocated with binalloc are added to
          the Bin pointed to by bp. All items in a bin may be freed
          with one call to binfree; there is no way to free a single
          item.

          Binalloc returns a pointer to a new block of at least size
          bytes.  The block is suitably aligned for storage of any
          type of object.  No two active pointers from binalloc will
          have the same value.  The call binalloc(0) returns a valid
          pointer rather than null.  If clr is non-zero, the allocated
          memory is set to 0; otherwise, the contents are undefined.

          Bingrow is used to extend the size of a block of memory
          returned by binalloc. Bp must point to the same bin group
          used to allocate the original block, and osize must be the
          last size used to allocate or grow the block.  A pointer to
          a block of at least size bytes is returned, with the same
          contents in the first osize locations.  If clr is non-zero,
          the remaining bytes are set to 0, and are undefined other-
          wise.  If op is nil, it and osize are ignored, and the
          result is the same as calling binalloc.

          Binalloc and bingrow allocate large chunks of memory using
          malloc(2) and return pieces of these chunks.  The chunks are
          free'd upon a call to binfree.

     SOURCE
          /sys/src/libbin

     SEE ALSO
          malloc(2)

     BIN(2)                                                     BIN(2)

     DIAGNOSTICS
          binalloc and bingrow return 0 if there is no available mem-
          ory.