my first take at a memory leak detection document

2 files changed, 50 insertions, 1 deletions

diff --git a/lib/Makefile.am b/lib/Makefile.am
index 746748537..8085d312c 100644
--- a/lib/Makefile.am
+++ b/lib/Makefile.am
@@ -7,7 +7,7 @@ AUTOMAKE_OPTIONS = foreign nostdinc
 EXTRA_DIST = getdate.y Makefile.b32 Makefile.b32.resp Makefile.m32	    \
        Makefile.vc6 Makefile.riscos libcurl.def dllinit.c curllib.dsp	    \
        curllib.dsw config-vms.h config-win32.h config-riscos.h config-mac.h \
-       config.h.in ca-bundle.crt README.encoding
+       config.h.in ca-bundle.crt README.encoding README.memoryleak
 
 lib_LTLIBRARIES = libcurl.la
 
diff --git a/lib/README.memoryleak b/lib/README.memoryleak
new file mode 100644
index 000000000..8402dc40e
--- /dev/null
+++ b/lib/README.memoryleak
@@ -0,0 +1,49 @@
+$Id$
+                                  _   _ ____  _     
+                              ___| | | |  _ \| |    
+                             / __| | | | |_) | |    
+                            | (__| |_| |  _ <| |___ 
+                             \___|\___/|_| \_\_____|
+
+             How To Track Down Suspected Memory Leaks in libcurl
+             ===================================================
+
+Build
+
+  Rebuild libcurl with -DMALLOCDEBUG (usually, rerunning configure with
+  --enable-debug fixes this). 'make clean' first, then 'make' so that all
+  files actually are rebuilt properly. It will also make sense to build
+  libcurl with the debug option (usually -g to the compiler) so that debugging
+  it will be easier if you actually do find a leak in the library.
+
+  This will create a library that has memory debugging enabled.
+
+Modify Your Application
+
+  Add a line in your application code:
+
+       curl_memdebug("filename");
+
+  This will make the malloc debug system output a full trace of all resource
+  using functions to the given file name. Make sure you rebuild your program
+  and that you link with the same libcurl you built for this purpose as
+  described above.
+
+Run Your Application
+
+  Run your program as usual. Watch the specified memory trace file grow.
+
+  Make your program exit and use the proper libcurl cleanup functions etc. So
+  that all non-leaks are returned/freed properly.
+
+Analyze the Flow
+
+  Use the tests/memanalyze.pl perl script to analyze the memdump file:
+
+    tests/memanalyze.pl < memdump
+
+  This now outputs a report on what resources that were allocated but never
+  freed etc. This report is very fine for posting to the list!
+
+  If this doesn't produce any output, no leak was detected in libcurl. Then
+  the leak is mostly likely to be in your code.