.\" $Xorg: README,v 1.3 2000/08/17 19:55:19 cpqbld Exp $

This library replaces the C library allocator;
providing malloc, free, realloc and calloc (sorry, no valloc)

In doing so, it provides extensive memory bug checking, locating:

	Lost memory; memory which has not been freed and which has no
	references

	In use free memory; memorhy which has been freed and still has
	references to it.

	Stores to freed memory

	free/realloc with invalid pointers -- if you pass in a pointer to
	the middle of an allocated block, it will even tell you which one

For each of these errors, a report entry is generated which includes
the stack backtrace of either the allocation or free (which ever occured
last) along with the current stack, when relevant.

Unreferenced allocated memory, stores to freed memory and referenced freed
memory are only caught when CheckMemory is called.  It is automatically
called each time 1m of data has been freed, and is called when the program
exits (by registering with atexit(3)/on_exit(3)).  You can call it whenever
you want.

Both the X server and font servers call CheckMemory after each reset when
their respective os/utils.c are compiled -DMEMBUG.

There are a few global variables you can set with the debugger to
help isolate problems:

	FindLeakWarnMiddlePointers
		Normally, memleak ignores pointers to the middle of
		freed memory.  These are frequently simply random data
		which happens to look like a pointer.  Turning this
		on will generate additional messages.
	FindLeakAllocBreakpoint
		At each allocation, memleak increments a serial number
		and stores it in the allocation header.  By rerunning
		the program, you can stop when that piece of memory
		is going to be allocated.  Store the serial number
		in this global variable and put a debugger breakpoint inside
		AddActiveBlock at the indicated line.
	FindLeakFreeBreakpoint
		Similarly for freeing memory.
	FindLeakTime
		The current serial number
	FindLeakCheckAlways
		When set, memleak checks the entire memory system after
		each allocation or free.  This is very expensive, but
		may catch errors not otherwise found until too late.

To include this in your application, simply place libmemleak.a before the
end of the link line; it will then override the C library allocator.

To port this system to a new machine, you must provide two values, one
indicating the lowest data address in a program and one indicating the
highest stack address.  In addition, to get return stack traces (which are
almost essential for debugging), you must provide the function
getReturnStack.  Samples for MIPS and SPARC are included already.

The output from the leak tracer includes only PC values in the stack
traces.  To convert these into useful values, run the output of
the leak tracer through the find-routines script; after making sure you have
built the modified version of gdb-4.4 on your machine.

-keith