mssdoc.htm

内存检测程序源代码

<TABLE CELLSPACING=2 CELLPADDING=4 BORDER=0 WIDTH="100%"><TR><TD BGCOLOR="#C0C0FF">
<FONT SIZE="+3"><FONT COLOR="#000080"><A NAME="configuring-mss"><B>4. Configuring MSS</B></A></FONT></FONT>
</TD></TR></TABLE>
<P>
<UL>
<A HREF="#general-information">4.1 General information</A><BR>
<A HREF="#configuration-file-syntax">4.2 Configuration file syntax</A><BR>
<A HREF="#specifying-where-to-write-logging-output">4.3 Specifying where to write logging output</A><BR>
<A HREF="#options-concerning-error-detection">4.4 Options concerning error detection</A><BR>
<A HREF="#options-concerning-the-layout-of-the-logfile">4.5 Options concerning the layout of the logfile</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-information"><B>
4.1 General information.
</B></A></FONT></FONT></TD></TR></TABLE>

<P>This chapter discusses the configuration which affects MSS while it is running, which mostly includes what kind of error checking to perform, and the layout of the logfile.</P>

<P>All compiler specific configurations should be made either in the makefile (if you are using GCC) as discussed in <A HREF="#compiling-and-installing-mss-using-gcc">Compiling and installing MSS using GCC</A>, or in `mss.h&acute; which is discussed in <A HREF="#configuring-mss-for-your-compiler">Configuring MSS for your compiler</A>.</P>

<P>All run-time specific configurations are either read from special configuration files at run-time, or the internal hard-coded values are used. The special configuration files does not need to contain <EM>all</EM> available configuration options, only the ones that it should override. The configuration is made in the following order;
</P>
<UL>
<LI>Internal hard-coded values are &quot;read&quot;.</LI>
<LI>Global configuration file (if present) is read, overriding the hard-coded values.</LI>
<LI>Local configuration file (if present) is read, overriding any previous read values.</LI>
</UL>
<P>There is no need to have any configuration file present, and in that case the hard-coded values are used. If you wish to use a <EM>global</EM> configuration file, this file will be read by any program that uses MSS, the environment variable `<CODE>MSS_CFG</CODE>&acute; should contain the full path to this file. The option `<CODE>LocalCFGFile</CODE>&acute; in this file specifies the name of the local configuration file (if this option is not available the hard-coded value `<CODE>mss.cfg</CODE>&acute; will be used. The <EM>local</EM> configuration file is always expected to be found in the directory from which the program is run (<B>NOTE</B> that your program must not change directories before the first call to an MSS function or a memory allocation function if the local configuration file should be found). If this files exists, any options available in it will override the options previously read from any global configuration file or the hard-coded values.</P>
<P>Please note that you do not need to have both configuration files present. You can choose only to have the <EM>local</EM> or the <EM>global</EM> file or none of them. It is however recommended that you create a global configuration file, so that you are sure on which options are enabled.</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="configuration-file-syntax"><B>
4.2 Configuration file syntax
</B></A></FONT></FONT></TD></TR></TABLE>

<P>The syntax of the configuration files is really simple, and is very similar to for an example the windows ini files except there are no sections.  The purpose of the configuration files are to set various options to diffrent values.  The general syntax is:</P>
<P><CODE>&lt;OptionName&gt; = [&quot;]&lt;Value&gt;[&quot;]</CODE></P>
Where <CODE>&lt;OptionName&gt;</CODE> is the name of the option, and <CODE>&lt;Value&gt;</CODE> is the value you wish to set this option to. The value can be quoted if you wish to, but this is not neccessary unless you want to include whitespaces at the beginning or the end of the value. There are some values that have a special meaning if a boolean (true/false) value it expected. You can set a boolean option to either &quot;True&quot;, &quot;1&quot; or &quot;Yes&quot; to specify a <EM>true</EM> value, or &quot;False&quot;, &quot;0&quot; or &quot;No&quot; to specify a <EM>false</EM> value. Note that all <EM>integer</EM> values can be specified in decimal <EM>or</EM> hexadecimal form (ex. <CODE>0x10</CODE>). If you want the option to include a quote (&quot;), a newline or some other special character you need to escape it. The following escape codes are recognized by MSS:</P>
<P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<TR VALIGN="top">
<TD BGCOLOR="#FFC0C0"><B>Escape Sequence</B></TD>
<TD BGCOLOR="#FFC0C0"><B>Meaning</B></TD>
</TR>
<TR VALIGN="top">
<TD BGCOLOR="#C0C0FF"><CODE>\\</CODE></TD>
<TD BGCOLOR="#C0C0FF">Single backslash</TD>
</TR>
<TR VALIGN="top">
<TD BGCOLOR="#C0C0FF"><CODE>\n</CODE></TD>
<TD BGCOLOR="#C0C0FF">Newline</TD>
</TR>
<TR VALIGN="top">
<TD BGCOLOR="#C0C0FF"><CODE>\r</CODE></TD>
<TD BGCOLOR="#C0C0FF">Carriage Return</TD>
</TR>
<TR VALIGN="top">
<TD BGCOLOR="#C0C0FF"><CODE>\&quot;</CODE></TD>
<TD BGCOLOR="#C0C0FF">Double Quote</TD>
</TR>
<TR VALIGN="top">
<TD BGCOLOR="#C0C0FF"><CODE>\t</CODE></TD>
<TD BGCOLOR="#C0C0FF">Tab</TD>
</TR>
</TABLE>
</P>
<P>Comments are also allowed in the config file, on an empty line. They should be preceeded by a <CODE>#</CODE>-sign.</P>
<P>Let's show you an example:</P>

<P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<TR BGCOLOR="#FFFFC0">
<TD>
<PRE>
# This is a comment
LogFileName = &quot;mss.cfg&quot;

# False and No have the same meaning.
LogToStdout = False
LogToStderr = No

NewLineString = &quot;\n&quot;
</PRE>
</TD></TR></TABLE></P>
<P><B>NOTE!</B> The configuration files are case-insensitive, that is &quot;LogFileName&quot; is equal to &quot;LOGFILENAME&quot; and &quot;logfilename&quot;.</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="specifying-where-to-write-logging-output"><B>
4.3 Specifying where to write log output
</B></A></FONT></FONT></TD></TR></TABLE>

</FONT></A></H2>
<P>Logging output can be written either to a file, or any of the standard output streams (stdout and stderr). This is controlled by the three configuration options `<CODE>LogFileName</CODE>&acute;, `<CODE>LogToStdout</CODE>&acute; and `<CODE>LogToStderr</CODE>&acute;.</P>
<P><TABLE BORDER="0" CELLSPACING="2" CELLPADDING="4">
<TR VALIGN="bottom" 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>LogFileName</CODE></TD>
<TD>String</TD>
<TD>The filename to which logging output will be written in case both `<CODE>LogToStdout</CODE>&acute; and `<CODE>LogToStderr</CODE>&acute; are set to false. They are described below</TD>
<TD><CODE>mss.cfg</CODE></TD>
</TR>

<TR VALIGN="top"  BGCOLOR="#C0C0FF">
<TD><CODE>LogToStdout</CODE></TD>
<TD>Boolean</TD>
<TD>If this is set to true logging output will be written to the standard output (stdout). Note that only one of `<CODE>LogToStdout</CODE>&acute; and `<CODE>LogToStderr</CODE>&acute; may be set to true at the same time, so always include both of these in the configuration file.</TD>
<TD><CODE>False</CODE></TD>
</TR>

<TR VALIGN="top"  BGCOLOR="#C0C0FF">
<TD><CODE>LogToStderr</CODE></TD>
<TD>Boolean</TD>
<TD>If this is set to true logging output will be written to the standard error (stderr). Note that only one of `<CODE>LogToStdout</CODE>&acute; and `<CODE>LogToStderr</CODE>&acute; may be set to true at the same time, so always include both of these in the configuration file.</TD>
<TD><CODE>False</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-error-detection"><B>
4.4 Options concerning error detection
</B></A></FONT></FONT></TD></TR></TABLE>


<P>There are a number of options that lets you specify diffrent methods which will either make MSS detect errors, or somehow make it easier for the programmer to detect them. They are listed below:</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>WatchLimits</CODE></TD>
<TD>Boolean</TD>
<TD>This option enables/disables the checking of out-of-bounds writes on dynamically allocated memory blocks. This is achieved by allocating some extra space on both sides of the memory block, and filling it with a specific value. Then upon deallocation of the block, or upon request from user, this extra space is checked. If it doesn't all contain the same value it was filled with then an out-of-bound writing has occured. It is recommended to have this option enabled. Although it wastes some memory, it is one of the most powerful features in detecting bugs.</TD>
<TD><CODE>True</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>WatchSize</CODE></TD>
<TD>Integer</TD>
<TD>This option specifies the size of the extra space allocated before and after any allocated blocks, if `<CODE>WatchLimits</CODE>&acute; was set to true. Bigger  values give more detection power, but also more waste of memory and the time spent checking blocks will increase.</TD>
<TD><CODE>32</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>WatchValue</CODE></TD>
<TD>Integer  (0-255)</TD>
<TD>This option specifies the value with which the extra space allocated before and after any allocated blocks if `<CODE>WatchLimits</CODE>&acute; was set to true. Set this to anything but zero.</TD>
<TD><CODE>0xA8</CODE></TD>
</TR>


<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>FillMemOnAlloc</CODE></TD>
<TD>Boolean</TD>
<TD>If this option is set to true, all memory allocated will be filled with a specific value (specified by `<CODE>FillMemOnAllocValue</CODE>&acute;). This is useful, since programmers often accidently rely upon uninitialized memory, which usually will be zero, but with this option enabled it will all be initialized to `<CODE>FillMemOnAllocValue</CODE>&acute;</TD>
<TD><CODE>True</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>FillMemOnAllocValue</CODE></TD>
<TD>Integer (0-255)</TD>
<TD>This option specifies the `byte&acute; value with which to fill memory upon allocation. (see `<CODE>FillMemOnAlloc</CODE>&acute;)</TD>
<TD><CODE>0x98</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>FillMemOnDealloc</CODE></TD>
<TD>Boolean</TD>
<TD>If this option is enabled all memory will be filled with a specific value (specified by `<CODE>FillMemOnDeallocValue</CODE>&acute; upon deallocation. This is useful, since programs often use memory after it has been deallocated (it even happened during the development of MSS, but we had a much harder time detecting it than you will have with this option enabled), and with this option
enabled those bugs will be easy to detect.</TD>
<TD><CODE>True</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>FillMemOnDeallocValue</CODE></TD>
<TD>Integer (0-255)</TD>
<TD>This option specifies the value with which to fill deallocated memory with. (see `<CODE>FillMemOnDealloc</CODE>&acute;).</TD>
<TD><CODE>0x86</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>CheckOnDealloc</CODE></TD>
<TD>Boolean</TD>
<TD>With this option enabled all blocks will be checked for out-of-bound writings and constant block corruption as they are deallocated. It is <EM>strongly</EM>recommended that you leave this enabled, since all blocks really should be checked upon deletion.</TD>
<TD><CODE>True</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>CheckAllOnAlloc</CODE></TD>
<TD>Boolean</TD>
<TD>If this option is set to true <EM><B>all</B></EM> blocks will be checked for out-of-bound writing and constant block corruptions <EM>every</EM> time a block is allocated/deallocated. This can be <EM>very</EM> time-consuming, and is usually not neccessary.</TD>
<TD><CODE>False</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>AllocFails</CODE></TD>
<TD>Integer (0-100)</TD>
<TD>This option should be a number between 0 and 100, which indicates how many percent of the times that malloc are called will fail, hence returning NULL. This is useful for stress-testing you application, to see if it can deal with out-of-memory situations. If this is set to ex. 50, malloc/calloc/realloc will return NULL about every second time it was called (average), even though they did not actually run out of memory. Set to zero to disable.</TD>
<TD><CODE>0</CODE></TD>
</TR>

<TR VALIGN="top" BGCOLOR="#C0C0FF">
<TD><CODE>ExitOnWarning</CODE></TD>
<TD>Boolean</TD>
<TD>If this option is enabled, MSS will exit the program as soon as a warning is written to the logfile. This option is disabled by default, but if your program crashes, and the logfile somehow disappears it might be useful to enable this option.</TD>