about the "chk" module

crux-00004: $SRC/utils/README.chk

* "chk": hard-failing memory allocation routines

  The "chk" functions are used to allocate memory in a manner
  similar to "malloc", "realloc", and "free".

  There are three differences.

  1) If an allocation fails, these routines do not return but
     instead call "panic" (see <<utils/README.panic>>).

  2) These routines keep track of how much memory they have
     allocated (net).  If an allocation request would exceed a
     preset limit, they call "panic".  3) Callers are obligated
     to remember the size of each allocated block, and pass this
     information back to the "realloc" and "free" functions.

* The "chk" interface

    #include "utils/chk.h"

    void chk_limit (int amt);
    void * chk_malloc (int amt);
    void * chk_realloc (void * m, int was_amt, int amt);
    void chk_free (void * m, int amt);

  The "chk_limit" function is used to set an upper bound on the
  (net) memory allocated by the other "chk" functions.  Callers
  must accurately supply "chk_free" and "chk_realloc" with the
  size of regions being freed or reallocated.

  A "chk_limit" limit of 0 means that allocation is unbounded
  and may continue until the underlying allocation functions

  "chk_limit" must not be called more than once and must not be
  called after calling any other "chk" function.

  If "chk_limit" is never called, the default limit is 1


    This file is part of Crux.

    Crux is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Crux is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Crux.  If not, see <http://www.gnu.org/licenses/>.