mssdoc.htm

内存检测程序源代码

<P>Now run "Project | Build all" to compile all libraries and test programs. Please note that all object files
are written into the same directory, so just running "Project | Make all" would produce corrupt libraries.</P>

<P>After that, all *.lib files can be found in the "lib\borland" subdirectory. All
test executables can be found in the "samples" subdirectory.</P>

<P>If you have trouble compiling MSS under Borland C++ v5.02, please feel free to
mail me under [e-mail]. However, please direct questions directly pertaining to MSS to 
<A HREF="mailto:[e-mail]">Peter Palotas at [e-mail]</A>.</P>


<P>&nbsp;</P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4" WIDTH="100%"><TR BGCOLOR="#FFFFC0"><TD><FONT SIZE=+2><FONT COLOR="#000080">
<A NAME="compiling-and-installing-mss-using-other-compiler"><B>
2.5 Compiling and installing MSS using another compiler
</B></A></FONT></FONT></TD></TR></TABLE>


<P>If you are using another compiler, you will have to write your own makefile or compile the library manually. The library should consist of the following files:</P>
<UL>
<LI><CODE>alloc.c</CODE></LI>
<LI><CODE>check.c</CODE></LI>
<LI><CODE>cppspec.cc (only if your compiler supports C++)</CODE></LI>
<LI><CODE>list.c</CODE></LI>
<LI><CODE>inifile.c</CODE></LI>
<LI><CODE>config.c</CODE></LI>
<LI><CODE>init.c</CODE></LI>
<LI><CODE>internal.c</CODE></LI>
<LI><CODE>log.c</CODE></LI>
<LI><CODE>inifile.c</CODE></LI>
<LI><CODE>user.c</CODE></LI>
</UL>

<P>You might have to rename the <CODE>.cc</CODE> files to <CODE>.cpp</CODE> for some compilers. (Probably for most DOS based ones).</P>

<P>After compiling these files and generating the library, the library and the include file `<CODE>mss.h</CODE>&acute; has to be copied to somewhere where your compiler will find them. Read the manual for your specific compiler.</P>

<P>MSS comes with a few documented sample programs that will show you some of MSS's capabilities and how you might use MSS to locate bugs. These files are located in the samples directory. See the file <CODE>README</CODE> in that directory for more information.</P>

<HR>
<TABLE CELLSPACING=2 CELLPADDING=4 BORDER=0 WIDTH="100%"><TR><TD BGCOLOR="#C0C0FF">
<FONT SIZE="+3"><FONT COLOR="#000080"><A NAME="using-mss"><B>3. Using MSS</B></A></FONT></FONT>
</TD></TR></TABLE>
<P>
<UL>
<A HREF="#how-to-make-your-program-use-mss">3.1 How to make your program use MSS</A><BR>
<A HREF="#functions-provided-by-mss">3.2 Functions provided by MSS</A><BR>
<A HREF="#what-do-these-warnings-mean">3.3 What do these warnings in the logfile mean?</A><BR>
<A HREF="#hints-and-tips">3.4 Hints &amp; Tips</A><BR>
<A HREF="#known-problems">3.5 Known Problems With MSS</A><BR>
</UL>
</P>

<P>&nbsp;</P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4" WIDTH="100%"><TR BGCOLOR="#FFFFC0"><TD><FONT SIZE=+2><FONT COLOR="#000080">
<A NAME="how-to-make-your-program-use-mss"><B>
3.1 How to make your program use MSS
</B></A></FONT></FONT></TD></TR></TABLE>

<P>Making your program use MSS is as we have mentioned earlier really simple. All you have to do is to add `<CODE>#include &lt;mss.h&gt;</CODE>&acute; at the very top of every C/C++ source file in your project. Note that you have to add this line to <I>all</I> files in your project, or MSS will not work correctly. To actually enable MSS you will also have to define the symbol <CODE>MSS</CODE>, and link your program with the MSS library.</P>

<P>If you are using GCC, you can simply define the <CODE>MSS</CODE> symbol by specifying <CODE>-DMSS</CODE> on the commandline to gcc, and specify <CODE>-lmss</CODE> to link with the MSS library. To achieve best performance, you should specify the MSS library as the very last library on the commandline. This is because MSS wants to know when your program exits, and if you don't specify MSS as the last library, it might think your program exits before it really does, due to the way destructors are called. (This does not affect C projects though, nor will it cause any errors or anything, it will just print that the program exits before it really does to the log file, hence making it look like some allocations/deallocations occured after the program exit. This is extremely rare though, and you normally don't have to worry about this).</P>

<P>Every call to '<CODE>new</CODE>', '<CODE>delete</CODE>', '<CODE>malloc</CODE>', '<CODE>calloc</CODE>', '<CODE>realloc</CODE>', '<CODE>xmalloc</CODE>', '<CODE>xrealloc</CODE>', '<CODE>cfree</CODE>', '<CODE>xfree</CODE>', '<CODE>free</CODE>' and '<CODE>strdup</CODE>' will be filtered and processed by MSS, and a logfile will be
created. (Or logging will be written to stdout/stderr, depending on your configuration). You might notice a minor(?) speed
degradation when running your program using MSS (sometimes, depending on how MSS is configured, the speed degradation can be very big, which might make you think the program has crashed), otherwise you shouldn't notice anything diffrent about your program. (Other than the fact that you probably will get fewer crashes). The logfile created will contain information about all allocated memory, when the allocations/deallocatios occured, if any errors has been detected and so on. Depending on the configuration options to MSS the logfile can sometimes become very large, so be aware of this so that you have enough free diskspace.</P>


<P>&nbsp;</P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4" WIDTH="100%"><TR BGCOLOR="#FFFFC0"><TD><FONT SIZE=+2><FONT COLOR="#000080">
<A NAME="functions-provided-by-mss"><B>
3.2 Functions provided by MSS
</B></A></FONT></FONT></TD></TR></TABLE>

<P>
MSS provides a lot of functions that your program might call to get information about the current memory situation, or affect the logging in some way which is what most of the functions do. All functions are called through macros, which all compiles away to nothing in case the preprocessor symbol '<CODE>MSS</CODE>' was not defined. This feature makes it easy to switch between &quot;debug&quot; and &quot;release&quot; mode, in case you want to for an example test the real speed with which your program will run this comes quite in handy.</P>

<P>For a complete reference of all the functions, see the <A HREF="#function-reference">Function Reference</A>.</P>


<P>&nbsp;</P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4" WIDTH="100%"><TR BGCOLOR="#FFFFC0"><TD><FONT SIZE=+2><FONT COLOR="#000080">
<A NAME="what-do-these-warnings-mean"><B>
3.3 What do those warnings in the logfile really mean?
</B></A></FONT></FONT></TD></TR></TABLE>

<P>The MSS logfile sometimes produces warnings which may seem strange at first, therefore we have decided to explain the meaning of some terms here.</P>

<TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><STRONG>Prefix Corrupted</STRONG></TD>
<TD BGCOLOR="#C0C0FF">You have written some data out of the limits of the described block. Specifically, you've done it <I>before</I> the start of the
block. This is mainly caused by using 'signed' numbers as array indexes or pointer displacements on some pointer arithmetic, so
you end up using negative indexes or displacements.</TD>
</TR>

<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><STRONG>Suffix Corrupted</STRONG></TD>
<TD BGCOLOR="#C0C0FF">You have written some data out of the limits of the described block. Specifically, you've done it <I>after</I> the end of the block. This is typically caused by array operations contained in loops that go 'too far'. Can also be caused by using a too small buffer to hold some data.</TD>
</TR>

<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><STRONG>Trying to delete a non-allocated block</STRONG></TD>
<TD BGCOLOR="#C0C0FF">There is no block allocated at the address that pointer points to. The main reasons for this are: 
<UL>
<LI>You have really not allocated any block for that pointer. </LI>
<LI>You did, but somehow the pointer has been altered and it's original value lost (maybe you where using it as an index?). </LI>
<LI>The pointer was correctly pointing to a block of allocated memory, but you have deallocated it before; that is, you are
deallocating it twice or more! To see if this is what happened, look for the same pointer value in the log file and see what you did to it.</LI>
</UL>
</TD>
</TR>

<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><STRONG>There is no block starting at 'address'</STRONG></TD>
<TD BGCOLOR="#C0C0FF">Same as above. This is issued when you request some info about a non existent block.</TD>
</TR>

<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><STRONG>Zero length allocation</STRONG></TD>
<TD BGCOLOR="#C0C0FF">You are requesting an allocation for a zero length block. Maybe some uninitialized variable or a logic or flow bug is causing this problem!?</TD>
</TR>

<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><STRONG>NULL pointer deallocation</STRONG></TD>
<TD BGCOLOR="#C0C0FF">You are deleting a pointer to NULL. This will probably result in a GP Fault, however it is actually legal in C++ (using delete) a
warning will still be printed, since you shouldn't do this. Some compilers may not like it! (This warning can be disabled for C++ though, but is normally enabled).</TD>
</TR>

<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><STRONG>Pointer 'p' does not point to any valid memory</STRONG></TD>
<TD BGCOLOR="#C0C0FF">You are dealing with a pointer that does not point to any legal allocated memory. MSS should tell you also what are the nearest
legal blocks. You've probably stepped out from any of them. You may also be using an uninitialized pointer.</TD>
</TR>
</TABLE>


<P>&nbsp;</P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4" WIDTH="100%"><TR BGCOLOR="#FFFFC0"><TD><FONT SIZE=+2><FONT COLOR="#000080">
<A NAME="hints-and-tips"><B>
3.4 Hints &amp; Tips
</B></A></FONT></FONT></TD></TR></TABLE>

<P>Here are some notes that you may find useful:

<UL>
<LI>First time users of MSS, please study the sample programs in the samples directory and their documentations. This is really useful for learning some of MSS's capabilities and how you might use it to debug your programs. See the file '<CODE>README</CODE>' in the <CODE>samples</CODE> directory for more information.
</LI>
</UL>

<UL>
<LI>
Keep in mind that all the values that MSS gives you (total memory used, blocks, etc...) ignore MSS own use of memory. That is, MSS is completely transparent to itself, so you can rely on this values being accurate. But notice that the <EM>real</EM> use of memory when using MSS is always higher due to it's own memory needs. They are not much, anyway; about 20-30 bytes by memory allocation proccessed. This is increased in WatchSize * 2 if WatchLimits is enabled. 
</LI>
</UL>

<UL><LI>
Be careful about disk space and logging options. An MSS log file with all options enabled can be really *big*, specially on big &amp; memory intensive programs. In a game I am writing (about 4000+ lines of code), I get a 900kb log file! Use MSS even if your program runs without problems and you think it has no bugs. It is *incredible* the amount of memory related bugs that can be hidind behind an apparent correct program. I did this with my game, which was giving no problems, and found *TONS* of bugs, some little, some really nasty. I also found a BIG memory leak... (in fact, I was frightened after reading the log file!).
</LI>
</UL>

<UL><LI>
Always remember what options where enabled when reading a log file. They are listed at the beginning of it. You may think you have no 'out of range write' bugs, while the reality is that MSS was not checking them! Note that 'out of range' write check is only done if you specifically invoke it at run time (with <CODE>MSS_CHECK_ALL_BLOCKS</CODE> or <CODE>MSS_CHECK_BLOCK_AT()</CODE>) or if <CODE>CheckOnDealloc</CODE> or <CODE>CheckAllOnAlloc</CODE> is enabled at compile time. 
</LI>
</UL>

<UL><LI>
If you only want to discover hidden bugs, put <CODE>MSS_DISABLE_LOG_OUTPUT</CODE> at the beginning of your program. This will make MSS log only the warnings, and not every legal memory operation. Anyway, it is a good practice to inspect at least once the 'memory allocation trace' generated by MSS by default. If you get a warning about trying to delete a non allocated block, enable <CODE>FillMemOnAlloc</CODE> and take a look at the direction of the offending pointer; if it is equal to <CODE>FillMemOnAllocValue</CODE>, then you are deleting a dynamically allocated uninitialized pointer. 0x98 is the default <CODE>FillMemOnAllocValue</CODE>. 
</LI>
</UL>

<UL><LI>
If your program crashes, look at the MSS logfile to see where the last memory operation was executed. This may give
you a hint to isolate the bug. It is useful to write little testing programs that create one object and then destroys it. You can use MSS to check if all memory has been deallocated successfully, or if it is still some memory reserved. This is specially useful to check the destructors of complex classes that do a lot of dynamic allocations/deallocations. An example: <BR>&nbsp;

<TABLE CELLSPACING="2" CELLPADDING="4" BORDER="0">
<TR><TD BGCOLOR="#FFFFC0">
<PRE>
#include &quot;ctree.h&quot;    //For complex tree class
#include &quot;mss.h&quot; //For MSS :)

int main(void)
{
        Ctree * my_tree= new Ctree; //I create a complex tree
        <...Do a lot of operations of node insertion...>
        MSS_LOG_INFO;       //To see number of blocks and memory used.
        delete my_tree; //Destroy the tree -> call destructor -> release memory
        MSS_LOG_INFO;       //To see if there is still any allocated memory.
        MSS_LOG_BLOCK_LIST; //To get detailed info about it.
        return 0;
}
</PRE>
</TD></TR></TABLE>
</LI>
</UL>

<UL><LI>
Remember, you must put the <CODE>#include &lt;mss.h&gt;</CODE> in ALL your <I>C</I> files to fully use MSS, or if you want to stop using MSS, you can either delete all <CODE>#include &lt;mss.h&gt;</CODE>, or not define 'MSS'. You also must <EM>not</EM> link the MSS library to your project. (If you are using only plain <I>C</I>, no <I>C++</I>, you can still link the library if you want to, making it very easy to disable MSS. Simply don't define '<CODE>MSS</CODE>'). If you forget putting <CODE>#include &lt;mss.h&gt;</CODE>in any of your project's <I>C++</I> files, MSS will <EM>not</EM> be able to get detailed info about memory allocations or deallocations (I mean line number, module name and function name), but it will still handle all loggings correctly. This loggings will appear as:  &quot;<CODE>LOG: unknown (line 0 of unknown) allocated 20 bytes at 51120.</CODE>&quot;.<BR>
The same applies to precompiled modules linked with your application. However, this does not apply to <I>C</I> files. If you forget to include `<CODE>mss.h</CODE>&acute; in your <I>C</I> files MSS will not intercept and detect any allocations/deallocations. 
</LI>
</UL>

<UL>
<LI>
Please, if you use MSS, <A HREF="#contacting-the-authors">mail us and tell us</A>. We'd really like to hear from you! Any comments, suggestions, etc... are
highly appreciated. Thanks :). 
</LI>
</UL>

<P>&nbsp;</P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4" WIDTH="100%"><TR BGCOLOR="#FFFFC0"><TD><FONT SIZE=+2><FONT COLOR="#000080">
<A NAME="known-problems"><B>
3.5 Known problems with MSS
</B></A></FONT></FONT></TD></TR></TABLE>

<P>Currently there is only a single serious known problem with MSS. If your 
program overloads the <CODE>operator new</CODE> your program will not work 
correctly with MSS. For example, this happens with libstdc++ from GCC 2.95.
(Look for workaround <A HREF="#streambuf.h">here</A>. Also if you make your 
own <CODE>#define free &lt;something&gt;</CODE> or any other allocation 
function MSS will not work. Currently we have no good solution to these 
problem, but there is a workaround available: insert #include &lt;no_mss.h&gt; 
before any problematic place and re-include &lt;mss.h&gt; afterwards. 

<HR>