m.c
---

   This module provides a more secure environment for programmes that
need to check their usage of memory allocation.

   It must be used consistently throughout a whole programme. To use it,
each call to one of the memory management functions must be replaced by
a call to the macro provided by the module, as follows:

      malloc (size)           m_ALLOC (size)
      calloc (count, size)    m_CALLOC (count, size)
      free (ptr)              m_FREE (ptr, size)
      realloc (ptr, size)     m_REALLOC (ptr, old_size, size)

and "m.h" must be included.

   When you do this, if you have -DTRACE=0 (or nothing) on the command
line, all the macros map straight back to the calls on the left; but
when you do -DTRACE=1, they turn into calls to the checking functions
defined in m.c.

   These have the following effects. Whenever a block of memory is
allocated, it is filled with a junk byte (0xA5), so that code that
relies on the contents being anything in particular will fail. Also, 4
extra bytes are allocated on the end, and these are filled with a
different junk byte (0xA7). Just before memory is freed, it is filled
with a third junk byte (0xA9), and the extra bytes are checked to see
that they still contain the junk written in at the beginning.

   Also, each block has a header invisibly preceding it that links all
the blocks together, in order of allocation. Each block also contains
the file name and line number at which it was allocated, and a guard
word (0xACCE55ED) at the very beginning to protect against overwriting
at the beginning of the block. The integrity of the system is checked on
every call to any of the functions.

   Two of the calls have extra arguments: the call m_FREE (ptr, size)
allows the client to specify the size it believes the block to have been
allocated with: the module checks this. If the client doesn't know, the
call m_FREE (ptr, 0) disables the check. Similary, m_REALLOC (ptr,
old_size, new_size) checks the size of the block before resizing it,
unless old_size == 0.

   The call

      m_SUMMARY ()

traces all this information to the current trace destination. If the
compiling was done with -DTRACE=0, it does nothing.
