Document --with-traced-allocations.

src/server/ram-smalloc.c

 /*
- * $Id: ram-smalloc.c,v 0.27 1999/05/15 22:54:37 ceder Exp $
+ * $Id: ram-smalloc.c,v 0.28 1999/05/20 09:19:24 ceder Exp $
  * Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996  Lysator Academic Computer Association.
  *
  * This file is part of the LysKOM server.
@@ -36,13 +36,59 @@
 #endif
 
 /*
- * Define TRACED_ALLOCATIONS to get traces from smalloc, srealloc and sfree.
- * Run the resulting lyskomd under gdb. Source trace-mem.gdb. Run
- * M-x resolve-trace (from handle-malloc-dump.el) on the resulting output.
+ * Finding memory leaks
+ * ====================
+ *
+ * This code contains some stubs that can be useful when hunting for
+ * memory leaks.  To use it, you must configure with
+ * --with-traced-allocations and recompile. You actually only need to
+ * recompile ram-smalloc.c and ramkomd.c after changing it, so "make
+ * -t; rm src/server/ram-smalloc.o src/server/ramkomd.o; make" is the
+ * fastest way to change between tracing and a normal compile.
+ *
+ * Run the resulting lyskomd under gdb, like this:
+ *            bash$ gdb lyskomd
+ *            (gdb) source trace-mem.gdb
+ *            (gdb) run
+ *            Where does the trace want to go today? [stderr] RET
+ * gdb will print a backtrace and continue whenever memory is
+ * allocated, reallocated or released.  The program itself will also
+ * print out some information.  The result is a long log file.
+ *
+ * Run M-x resolve-trace (from handle-malloc-dump.el on the resulting
+ * output.  Look in the *Result* buffer for the result.
+ *
+ * Using the test suite to find memory leaks
+ * =========================================
+ *
+ * This code can also be used together with the test suite, even
+ * though that is slightly more complicated.  Begin by starting a gdb
+ * whose output is saved, for example by running it in a shell buffer
+ * in emacs (note: do not use M-x gdb -- that will slow down the
+ * process and it is slow enough as it is):
+ *            bash$ gdb lyskomd
+ *            (gdb) source trace-mem.gdb
+ *            (gdb) shell tty
+ *            /dev/ttypd
+ * Insert the following two statements in the *.exp script before the
+ * call to lyskomd_start that you want to trace:
+ *	      set attach 1
+ *            set MEMTRACE /dev/ttypd
+ * MEMTRACE should be set to the tty where gdb is running.  Start the
+ * test suite:
+ *	      bash$ runtest --tool lyskomd leaks.0/99.exp
+ *            [...]
+ *            Please attach to lyskomd pid 4711 and hit RETURN
+ * Attach to the process:
+ *            (gdb) attach 4711
+ *            (gdb) continue
+ * Press enter to resume the test suite.  Lots of output should appear
+ * from gdb.
+ *
  */
 
 static const char *
-rcsid = "$Id: ram-smalloc.c,v 0.27 1999/05/15 22:54:37 ceder Exp $";
+rcsid = "$Id: ram-smalloc.c,v 0.28 1999/05/20 09:19:24 ceder Exp $";
 #include "rcs.h"
 USE(rcsid);