SafeMem V2.0: A memory management safety net.
               ---------------------------------------------
                        written by Simon P. Bullen

	Contents
	--------
	In this archive, there should be the following files:

		FileName		Size
		-------------------	------
		makefile		326
		SafeMem.c		12960
		safemem.doc		5326
		SafeMem.h		1839
		safemem.lib		13032
		SafeMem_parallel.c	2931
		SafeMem_parallel.h	277
		test			9056
		test.c			342
		-------------------	------
		Total:			46089   

	Legal Stuff
	-----------
	This  software  is not public domain.  All material in this archive
is  ©  Copyright Simon P.  Bullen.  The software is freely distrubtable, so
long  as  no  more  than a nominal fee is charged for media.  Everything in
this distrubution must be kept together, in original, unmodified form.
	The  files  may be modified for your own personal use, but modified
files  must  not  be distributed.  No commercial usage is permitted without
written permission from the author.
	The material is provided "as is" without warranty of any kind.  The
author accepts no responsibilty for damages caused by this software.

	Contributions
	-------------
	If  you  have  any  suggestions,  remarks,  bugs or gratifications,
please write to me at

	s914373@minyos.xx.rmit.OZ.AU (until the end of 1993)

	or

	Simon P. Bullen
	PO BOX 12138
	A'Beckett St
	Melbourne 3000
	Australia


	INTRODUCTION
	------------
	Ever had the problem of a program you're trying to debug swallowing
24  bytes  somewhere,  and  not  knowing  where?  Or perhaps you're playing
around  with  one of the more complex memory structures, and it gurus a lot
due to incorrect memory frees?  Painful to debug, aren't they?

	Well, no longer!!  With SafeMem installed, your programs will crash
from memory mismanagement never again!

	SafeMem  is  a small link library that places a "safety net" around
all  your  calls to AllocMem(), AllocAbs(), FreeMem(), malloc(), realloc(),
calloc()  and  free().   It  traps errors such as freeing a block you never
owned,  freeing  a block twice, freeing a block with an incorrect size, and
never freeing a block at all.

	SafeMem  is  intended  as a development tool - use it while you are
writing  & debugging your programs, then when it's finished & bug free, you
recompile it again without SafeMem.


	USAGE
	-----
	SafeMem   is  intended  as  a  development  tool  for  use  with  C
programming, although header files could be constructed to make it function
with other languages.

	To install it, simply 

	#define SAFEMEM
	#include "safemem/safemem.h" /* this must be AFTER your exec protos & 
	                              * pragmas  
	                              */

	You  must  do  this  to every source module, otherwise you will run
into  problems  when  a  non-safemem  module  frees  some  memory  that was
allocated by a safemem module.  You must also link with safemem.lib.

	If  you  don't  include the #define, then the SafeMem routines will
compile  away to nothing.  During your program, you may call AllocMem, etc,
just  as  usual,  and  the  SafeMem  routines  will be transparently called
instead.

	As well as the normal memory management routines, you get two extra
functions - ShowMemList() and FreeMemList().

	ShowMemList()  displays  a list of all the memory that has not been
freed  at  this  time.   (If there is no unfreed memory, ShowMemList() does
nothing).

	test.c 17: Memory List
	    Address      Size         File             Line
	    -------      ----         ----             ----
	    $794ea68     1024         test.c           13

	FreeMemList()  frees  all  remaining memory on the memory list.  If
FreeMemList() actually finds something to free, it also prints a message:

	test.c 18: Freeing Memory List


	DISABLING SAFEMEM WITHOUT RECOMPILING EVERYTHING
	------------------------------------------------
	There is a global variable, gbl_SafeMem, which provides an override
for the safemem functions.  When gbl_SafeMem is 0, the safemem routines are
disabled (gbl_SafeMem defaults to 1).


	REDIRECTING THE ERRORS TO SOMETHING OTHER THAN STDOUT
	-----------------------------------------------------
	There  are times when printing the errors to stdout is unacceptable
-  when  you  are  debugging  multiple  tasks,  for  example (Tasks are not
permitted to use dos function such as Write).
	All  the  SafeMem  output  is  funnelled  through a function called
gbl_SafeMemOutput,  which is actually a pointer to a function, so it can be
reassigned.
	To  redirect  the  output  through  a different function, merely do
something like this:

	void ExampleOutputFunction(char *Text)
	{
	  fprintf(stderr, Text);
	}
	
	main()
	{
	  gbl_SafeMemOutput = ExampleOutputFunction;
	  ..
	}

	Provided  in  this library is a set of functions that will redirect
the  output to the parallel port.  To use them, all you need do is (as well
as  the  normal procedure):

	#include "safemem_parallel.h"
	
	main()
	{
	  OpenSafeMemParallel(); /* You should probably check the return
	                          * code of this function to make sure
	                          * it opened ok 
	                          */
	..
	
	..
	  CloseSafeMemParallel();
	}

	The  parallel  port  routines  could  easily  be adapted to use the
serial port instead.