readme.txt

Extended C/C++ Dynamic Memory Control And Debug Library

XMEM - Extended C/C++ Dynamic Memory Control And Debug Library
==============================================================

Copyright (c) 1987-2008, Juergen Mueller

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, 
are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this 
  list of conditions and the following disclaimer. 

- Redistributions in binary form must reproduce the above copyright notice, 
  this list of conditions and the following disclaimer in the documentation 
  and/or other materials provided with the distribution. 

- Neither the name of Juergen Mueller nor the names of its contributors 
  may be used to endorse or promote products derived from this software 
  without specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Written by: Juergen Mueller, D-70806 Kornwestheim, GERMANY
EMail: [e-mail]


Overview
========

The  extended C/C++ Dynamic Memory Control and Debug Library XMEM is a replacement
library for malloc/free and new/delete to find memory leaks and other memory related 
errors in C/C++ code. The implementation of XMEM is influenced from various sources 
like the authors personal experiences as software developer, articles in Dr. Dobb's 
Journal (DDJ) and other journals about dynamic memory allocation problems, public 
available source codes and features provided by commercial tools.

XMEM is easy to use: Include the header file xmem.h in your source files, add the 
implementation file xmem.c to your project, set the XMEM defines and recompile and 
link your project. XMEM is highly configurable and it provides extensive error and 
problem reporting and call trace logging. It is usable on different platforms like 
32 bit Windows (XP/Vista/2000), 16 bit Windows, 16 bit DOS, 32 bit extended DOS, 
32 bit Unix or Linux with many compilers.

The Windows XP/Vista/2000 C++ version of XMEM can be configured to use the function 
call interception and redirection technology "Detours", which is developed and 
provided by Microsoft Research Laboratories (research.microsoft.com). See Links 
for info how to get, install and use "Detours".

The Windows XP/Vista/2000 C++ version of XMEM can be configured to provide call 
stack tracing functionality based on "StackWalker" which can be found at The Code 
Project (www.codeproject.com). See Links for more info about "StackWalker" and how 
to get it.

The Windows XP/Vista/2000 version of XMEM can be configured to send trace info 
that can be received and displayed with XMEM Browser, a C#/.NET application.

All Microsoft Visual Studio example projects use default language compiler settings
to produce code depending on the file extensions (.c, .cpp). The C++ file versions 
are used by default. If pure C projects are preferred the projects have to be edited 
by changing the files from the .cpp to the .c versions.

The GNU C versions were tested with Delorie DJGPP GNU C/C++. They can be compiled 
from the command line. For this a batch file named gnu.bat is needed to set the 
necessary paths and environment variables. The Cygwin GNU C/C++ compiler is also
supported. To make DJGPP GNU C/C++ and Cygwin GNU C/C++ work, modifications to
the batch files may be necessary.

The AspectC++ code is experimental. It shall demonstrate how aspect oriented 
programming can be used for XMEM code instrumentation.

XMEM is developed and tested on Microsoft Windows XP Professional SP3 and may 
also work on Windows Vista and Windows 2000. Some features like Detours or 
StackWalker will only work on these systems. However, the basic XMEM features, 
especially those which compile with GNU C/C++, may also work on other systems 
like Linux.


Limitations
===========

XMEM currently supports only 16 and 32 bit pointers (sizeof(void *) == 2 or == 4).
XMEM is not yet tested on 64 bit systems.
XMEM is not yet fully multithread-safe.
XMEM significantly reduces the application performance and increases the 
amount of memory being used, depending on the options enabled:
- an application with XMEM enabled runs about 3 times slower than without XMEM
- an application with XMEM call stack tracing enabled runs about 15 times slower 
  than without XMEM (call stack tracing itself is about 5 to 6 times slower 
  compared to "pure" XMEM)
XMEM does only find problems in instrumented source code, but not in system or 
3rd party code (although the Detours or Library feature may catch such calls).
XMEM logging may have problems in C++ with destruction of static objects done 
after leaving main() function due to the destruction order which cannot be 
influenced because this is linker dependent.
XMEM compiled for C++ may be confused with new and delete calls from sources 
other than those being processed with xmem.h.


Links
=====

XMEM: http://sourceforge.net/projects/xmem
XMEM: http://www.geocities.com/sxtsoftware3/sxt_freesoftware.htm
XFILE: http://www.geocities.com/sxtsoftware3/sxt_freesoftware.htm
Detours: http://research.microsoft.com/sn/detours/
StackWalker: http://www.codeproject.com/threads/StackWalker.asp
General memory debugging info: http://www.geocities.com/jmsxt/swdev3.htm
DJGPP GNU C/C++: http://www.delorie.com/djgpp
AspectC++: http://www.aspectc.org


XMEM directory structure
========================

xmem                      Project root directory, source code
+--XMEMBrowser            XMEM Browser, C#/.NET application to display XMEM runtime information (experimental)
+--xmemgc                 Garbage Collection test project (Microsoft Visual Studio 2005 (MS VS))
+--xmemgc.gcc             Garbage Collection test project (Delorie DJGPP GNU GCC)
+--xmemperf               Performance test project (MS VS)
+--xmemperf.gcc           Performance test project (Delorie DJGPP GNU GCC)
+--xmemtest               Basic functionality test project (MS VS)
+--xmemtest.aspc          AspectC++ test projects (experimental)
|  +--example1            AspectC++ example 1
|  \--example2            AspectC++ example 2
+--xmemtest.browser       Basic functionality test project with XMEM_BROWSER output enabled (MS VS)
+--xmemtest.c_            Basic functionality test project C-language (MS VS)
+--xmemtest.c_.linux      Basic functionality test project C-language (Linux)
+--xmemtest.callstack     Basic functionality test project with call stack tracing (MS VS)
+--xmemtest.cygwin        Basic functionality test project (Cygwin GNU GCC)
+--xmemtest.detours.v15   Basic functionality test project with Detours v1.5 call redirection (MS VS)
+--xmemtest.detours.v21   Basic functionality test project with Detours v2.1 call redirection (MS VS)
+--xmemtest.gcc           Basic functionality test project (Delorie DJGPP GNU GCC)
+--xmemtest.ia64          Basic functionality test project (Microsoft Visual Studio 2008 Itanium 64 bit cross compiler)
+--xmemtest.library       Basic functionality test project with library call redirection (MS VS) (experimental)
+--xmemtest.linux         Basic functionality test project with library call redirection (Linux)
+--xmemtest.msgbox        Basic functionality test project with message boxes (MS VS)
+--xmemtest.msvc          Basic functionality test project (Microsoft Visual C++ 1.5)
+--xmemtest.pur           Basic functionality test project *without* XMEM (MS VS)
+--xmemtest.pur.gcc       Basic functionality test project *without* XMEM (Delorie DJGPP GNU GCC)
+--xmemtest.thread        Basic functionality test project for multi threading (MS VS)
+--xmemwell               Simple test project without errors (MS VS)
\--xmemwell.gcc           Simple test project without errors (Delorie DJGPP GNU GCC)


History
=======

Date        Version
25.06.2008  1.32    changed handling of source location tracing for nested calls to 
                    C++ operator delete, source location for MS VC 1.5 fixed, 
                    tracing of _expand(), HTML log file output, changes for 64 bit 
                    pointers (experimental), XMEMBrowser application updated, 
                    some more changes/extensions/corrections
16.11.2007  1.31    bug fixes, some extensions and optimizations, code changes for 
                    Linux, source code comments added, documentation updated, 
                    MAKE file for Linux added                                        
20.09.2007  1.30    XMEM Browser application for runtime info displaying added, 
                    message output for XMEM Browser added (option XMEM_BROWSER), 
                    improved recognition of inconsistent new[] / delete / free calls,
                    multi threading (handling of concurrent calls),
                    error for small model (2 byte pointer) compilation fixed,
                    output of program settings to error logfile, changes to 
                    StackWalker call stack output, some rework to message strings, 
                    problem with NULL pointer in logfile output string fixed, 
                    optional displaying messages in Windows message boxes,
                    wrong internal warnings in logfile removed, changes for GNU GCC 4.21
05.05.2007  1.29    changes to xmemtest and StackWalker, output redesigned
11.01.2007  1.28    update for latest Detours v2.1 release
18.11.2006  1.27    statistics extended, call stack tracing speed significantly improved 
                    (now more than 6 times faster than before)
02.10.2006  1.26    minor changes, project files updated
28.09.2006  1.25    changes to xmemtest and StackWalker, project files updated
24.09.2006  1.24    changes to call stack tracing
22.09.2006  1.23    call stack tracing with "StackWalker" added, some more minor changes
10.07.2006  1.22    bug fixes for Detours v2.1 changes
08.07.2006  1.21    changes for Detours v2.1
24.04.2006  1.20    changes for AspectC++, readme.txt for AspectC++ examples extended
17.04.2006  1.19    changes for Cygwin and AspectC++, AspectC++ example projects
10.04.2006  1.18    problem with hashvalue calculation fixed, small comment changes
19.02.2006  1.17    small bug fixes, project files updated to MS Visual Studio 2005, 
                    compiler option /FC added, changes for ISO C++, OutputDebugString 
                    changed, changes for 64 bit compilation, test for MS VC 1.5 16 bit 
                    compiler added, changes for GNU GCC 4.01
13.06.2005  1.16    small changes
22.01.2005  1.15    clean-up error corrected
06.01.2005  1.14    small changes for GNU C 3.43
11.10.2004  1.13    projects and batch files updated
17.06.2004  1.12    readme.txt updated, reference to XFILE added
28.05.2004  1.11    type conflicts solved, new project added
12.05.2004  1.10    all projects updated, xmemtest project with Detours call redirection 
                    added
06.12.2003  1.9     project files converted to MS Visual Studio .NET 2003
11.08.2003  1.8     bug fixes, some extensions
05.08.2003  1.7     C++ specific functions for GNU-C 3.23 changed
03.08.2003  1.6     update
26.07.2003  1.5     batch files for GNU compilation fixed and optimized
20.07.2003  1.4     code changes, projects redesigned, new projects added
13.06.2003  1.3     extensions
04.03.2003  1.2     realloc problem addressed
28.02.2003  1.1     readme.txt added
25.02.2003  1.0     initial publication