mssdoc.htm

内存检测程序源代码

<TD><CODE>False</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>WarnOnAllNULLDeallocs</CODE></TD>
<TD>Boolean</TD>
<TD>If this option is set to true, MSS will always warn you when trying to deallocate a NULL-pointer using the The reason this warning can be disabled, is because it is <EM>legal</EM> to deallocate a NULL-pointer according to the ANSI C/C++ standard. However, some compilers do not like this, and crash if you try to deallocate a NULL-pointer, so it's always good practice to check for NULL-pointers before deallocating memory.</TD>
<TD><CODE>True</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>ZeroLenAllocReturnNULL</CODE></TD>
<TD>Boolean</TD>
<TD>If this option is set to true, MSS will always return NULL if the user program tries to allocate a block sized zero bytes, rather than passing the request to the standard library allocation function. It is recommended to have this option enabled, and it is by default.</TD>
<TD><CODE>True</CODE></TD>
</TR>

</TABLE>
</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="options-concerning-the-layout-of-the-logfile"><B>
4.5 Options concerning the layout of the logfile
</B></A></FONT></FONT></TD></TR></TABLE>

<P>There are also a couple of options that controls the layout of the logfile, they are listed here.</P>

<P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<TR VALIGN="top" BGCOLOR="#FFC0C0">
<TD><B>Option Name</B></TD>
<TD><B>Type</B></TD>
<TD><B>Description</B></TD>
<TD><B>Default</B></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>ShowLogs</CODE></TD>
<TD>Boolean</TD>
<TD>With this option enabled all normal log messages (successful operations) will be written to the logfile, if it's disabled no normal log messages will be written to the logfile. (This can be overridden by function calls, see the <A HREF="#function-reference">Function Reference</A>).</TD>
<TD><CODE>True</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>ExtraNewline</CODE></TD>
<TD>Boolean</TD>
<TD>If this option is enabled, there will be an extra newline written to the logfile, between each log/warning message. This will make the logfile more readable.</TD>
<TD><CODE>True</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>WordWrap</CODE></TD>
<TD>Boolean</TD>
<TD>This option defines wether or not the logfile should be word-wrapped.</TD>
<TD><CODE>True</CODE></TD>
</TR>
</TABLE>
</P>
<HR>




<TABLE CELLSPACING=2 CELLPADDING=4 BORDER=0 WIDTH="100%"><TR><TD BGCOLOR="#C0C0FF">
<FONT SIZE="+3"><FONT COLOR="#000080"><A NAME="function-reference"><B>5. Function Reference</B></A></FONT></FONT>
</TD></TR></TABLE>
<P>
<UL>
<A HREF="#general-function-information">5.1 General information</A><BR>
<A HREF="#reference-function">5.2 Reference</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="general-function-information"><B>
5.1 General information
</B></A></FONT></FONT></TD></TR></TABLE>

<P>MSS provides a number of functions, that either controls the behaviour of MSS or outputs some information to the logfile. All calls are made through macros, and all of these macros expand to nothing if the symbol `<CODE>MSS</CODE>&acute; was not defined, which is useful for switching between &quot;debug&quot; and &quot;release&quot; mode when compiling your program. (Don't forget not to link the mss library with your program if you are using C++ and want to test a &quot;release&quot; version of your program).</P>

<P>Note that the MSS macros should not have any parenthesis after them in case the function takes no arguments. See this example:</P>
<P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<TR BGCOLOR="#FFFFC0"><TD>
<PRE>
char *ptr = new char[10];
strcpy(ptr, &quot;Hello&quot;);
MSS_DISABLE_LOG_OUTPUT;
MSS_REGISTER_CONSTANT_BLOCK(ptr);
MSS_ENABLE_LOG_OUTPUT;
...
</PRE>
</TD></TR></TABLE></P>
<P>As you see the `<CODE>MSS_DISABLE_LOG_OUTPUT</CODE>&acute; macro is called <EM>without</EM> any trailing empty parenthesis ().</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="reference-function"><B>
5.2 Reference
</B></A></FONT></FONT></TD></TR></TABLE>


<P>This is the MSS function reference. (Actually macro reference, but all macros call functions so...)</P>

<P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<CAPTION ALIGN="top"><B>Functions macros that returns nothing and prints all output to the logfile<B></CAPTION>
<TR VALIGN="top" BGCOLOR="#FFC0C0">
<TD><B>Function name</B></TD>
<TD><B>Description</B></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_LOG_INFO</CODE></TD>
<TD><P>This command writes general info about the present memory state to the logfile. The info written is:</P>
<UL>
<LI>The number of blocks currently allocated</LI>
<LI>The amount of memory currently used</LI>
<LI>The maximum amount of memory used since program start</LI>
<LI>The number of calls to allocation/deallocation functions.</LI>
<LI>The number of successful allocations/deallocations.</LI>
</UL>
<P>Please note that all memory references done by MSS are about dynamically allocated memory, MSS does not proccess static or automatic memory usage.</P>
</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_LOG_INTERNAL_INFO</CODE></TD>
<TD><P>This command lists some information about how much memory MSS actually uses, how much memory is wasted by the `<CODE>WatchLimits</CODE>&acute; option and so on, to the logfile. It is not really useful for program debugging, but it's there in case you want to know anyway.</P>
</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_LOG_BLOCK_LIST</CODE></TD>
<TD>This command outputs a list of all currently allocated blocks to the logfile, together with information about where that block was
allocated, by what function, the size of it and so on. A little warning is probably in place though, the output can be quite long if there is a lot of blocks allocated. (Just look at the test programs).</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_LOG_BLOCK_LIST_FILTERED(func)</CODE></TD>
<TD>This command iterates through the list of currently allocated blocks, and calls a user-supplied callback function for each block. This allows for selective inspection of block contents or selective block lists. The user-supplied callback function must be of the following type: <CODE>int callback_func(char *out, void *block, unsigned int size, const char *label, const char *file, const char *function, unsigned int line);</CODE> where <CODE>block</CODE> is a pointer to the block, <CODE>size</CODE> is the size of the block, <CODE>label</CODE> is a string containing the label of the block if any has been set, or <CODE>NULL</CODE> otherwise, <CODE>file, function, line</CODE> represents the file, line and function in which the block was allocated. (The function might not be correct if your compiler does not support a FUNCTION macro).<BR>All the output of this function that you want written to the logfile should be written into <CODE>out</CODE> which points to an empty string. (see Sample 2 for an example).<BR>&nbsp;<BR>Exactly what the callback function does is not relevant as long as:<BR>
<UL>
<LI>it does not alter the data passed to it (except for <CODE>out</CODE>)</LI>
<LI>it does not write more than 1023 characters to <CODE>out</CODE></LI>
</UL>
</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_CHECK_ALL_BLOCKS</CODE></TD>
<TD>This command checks <EM>all</EM> allocated blocks for out-of-bound writings and corrupted constant blocks. This command is only effective if MSS was compiled with the WatchLimits option enabled (see <A HREF="#options-concerning-error-detection">Configuring MSS</A>).</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_CHECK_BLOCK_AT(ptr)</CODE></TD>
<TD>This command checks the specified block starting at `<CODE>ptr</CODE>&acute; for out-of-bound writings and if block was registered at constant also for corruption. This command is only effective if MSS was compiled with the WatchLimits option enabled (see <A HREF="#options-concerning-error-detection">Configuring MSS</A>).</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_CHECK_POINTER_VALIDITY(ptr)</CODE></TD>
<TD>This command tells you if the specified pointer `<CODE>ptr</CODE>&acute; points to a legal (dynamically allocated) block of memory (not only the start of the block, but anywhere in a block). If not this command will write the nearest block start and block end, and the distance (in bytes) from the pointer to both start and end to the logfile.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_LOG_MSG(str)</CODE></TD>
<TD>This command simply writes the specified string `<CODE>str</CODE>&acute; to the logfile.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_DISABLE_LOG_OUTPUT<BR>MSS_ENABLE_LOG_OUTPUT</CODE></TD>
<TD>Disabling <EM>log</EM>-output prevents all <EM><B>legal</B></EM> allocation or deallocation messages to be written to the log file. They are processed by MSS, but silently. Warnings and command outputs are still written anyway.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_LOG_MSG(str)</CODE></TD>
<TD>This command simply writes the specified string `<CODE>str</CODE>&acute; to the logfile.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_STARTUP</CODE></TD>
<TD>This command initializes MSS. It is good practice to use this in the very beginning of your program, however not neccessary. If you are registering a function with atexit() before doing any memory allocations though, it is strongly recommended that you put this command <EM>before</EM> the call to atexit.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_SET_BLOCK_LABEL(ptr, str)</CODE></TD>
<TD>This command will give the block pointed to by `<CODE>ptr</CODE>&acute; the label specified by `<CODE>str</CODE>&acute;. This label will then be written to the logfile whenever a warning/message is written that involves this pointer. This is useful for keeping track of pointers.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_DUMP_BLOCK(ptr, filename)</CODE></TD>
<TD>This command will generate a raw binary dump of the memory contents pointed to by `<CODE>ptr</CODE>&acute; and write it to the file specified by `<CODE>filename</CODE>&acute;.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_REGISTER_CONSTANT_BLOCK(ptr)<BR>MSS_UNREGISTER_CONSTANT_BLOCK(ptr)</CODE></TD>
<TD>These commands registers/unregisters the block starting at `<CODE>ptr</CODE>&acute;, as a constant block. When a block is registered as constant it means that the contents of that block may not be changed, and MSS will print a warning if they are, the next time this block is checked. This function uses a very simple checksum method, that simply adds all the bytes in the block together. This is not very bullet proof, but the chance is pretty big that a bug will be detected by this method.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_ENTER_SCOPE<BR>MSS_LEAVE_SCOPE</CODE></TD>
<TD><P>These commands are useful, if you want to make sure that all blocks that are allocated within a scope are deallocated at the end of that scope. Simply enclose the scope you want to check with `<CODE>MSS_ENTER_SCOPE;</CODE>&acute; at the top and
`<CODE>MSS_LEAVE_SCOPE;</CODE>&acute; at the end.</P>
<P>(This function only checks the number of allocated blocks, so it might fail to detect a bug the way you want it, however this should be quite unlikely).</P>
<P>A warning will be printed at the termination of the program (or what MSS believes is the termination of the program anyway) if
the number of <CODE>MSS_ENTER_SCOPE</CODE>'s don't match the number of <CODE>MSS_LEAVE_SCOPE</CODE>'s executed.</P></TD>
</TR>
</TABLE>

<P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<CAPTION ALIGN="top"><B>Functions macros that returns a value (`<CODE>unsigned int</CODE>&acute;) to the caller and prints nothing to the logfile<B></CAPTION>

<TR VALIGN="top" BGCOLOR="#FFC0C0">
<TD><B>Function name</B></TD>
<TD><B>Description</B></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_CURRENTLY_USED_MEM</CODE></TD>
<TD>Returns the amount of currently allocated memory, not including the extra memory wasted by MSS internally.</TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>MSS_MAXIMU