manual-core.html

memory checking tool 源代码valgrind-3.2.1.tar.gz 这是英文使用手册

</p>
<pre class="programlisting">
==12345== some-message-from-Valgrind</pre>
<p>
</p>
<p>The <code class="computeroutput">12345</code> is the process ID.
This scheme makes it easy to distinguish program output from Valgrind
commentary, and also easy to differentiate commentaries from different
processes which have become merged together, for whatever reason.</p>
<p>By default, Valgrind tools write only essential messages to the
commentary, so as to avoid flooding you with information of secondary
importance.  If you want more information about what is happening,
re-run, passing the <code class="option">-v</code> flag to Valgrind.  A second
<code class="option">-v</code> gives yet more detail.
</p>
<p>You can direct the commentary to three different places:</p>
<div class="orderedlist"><ol type="1">
<li>
<p><a name="manual-core.out2fd"></a>The default: send it to a file descriptor, which is by default
    2 (stderr).  So, if you give the core no options, it will write
    commentary to the standard error stream.  If you want to send it to
    some other file descriptor, for example number 9, you can specify
    <code class="option">--log-fd=9</code>.</p>
<p>This is the simplest and most common arrangement, but can
    cause problems when valgrinding entire trees of processes which
    expect specific file descriptors, particularly stdin/stdout/stderr,
    to be available for their own use.</p>
</li>
<li>
<p><a name="manual-core.out2file"></a>A less intrusive
    option is to write the commentary to a file, which you specify by
    <code class="option">--log-file=filename</code>.  Note carefully that the
    commentary is <span><strong class="command">not</strong></span> written to the file you
    specify, but instead to one called
    <code class="filename">filename.12345</code>, if for example the pid of the
    traced process is 12345.  This is helpful when valgrinding a whole
    tree of processes at once, since it means that each process writes
    to its own logfile, rather than the result being jumbled up in one
    big logfile.  If <code class="filename">filename.12345</code> already exists,
    then it will name new files <code class="filename">filename.12345.1</code>
    and so on.</p>
<p>If you want to specify precisely the file name to use, without
    the trailing <code class="computeroutput">.12345</code> part, you can
    instead use <code class="option">--log-file-exactly=filename</code>.</p>
<p>You can also use the
    <code class="option">--log-file-qualifier=&lt;VAR&gt;</code> option to modify
    the filename via according to the environment variable
    <code class="varname">VAR</code>.  This is rarely needed, but very useful in
    certain circumstances (eg. when running MPI programs).  In this
    case, the trailing <code class="computeroutput">.12345</code> part is
    replaced by the contents of <code class="varname">$VAR</code>.  The idea is
    that you specify a variable which will be set differently for each
    process in the job, for example
    <code class="computeroutput">BPROC_RANK</code> or whatever is
    applicable in your MPI setup.</p>
</li>
<li>
<p><a name="manual-core.out2socket"></a>The
    least intrusive option is to send the commentary to a network
    socket.  The socket is specified as an IP address and port number
    pair, like this: <code class="option">--log-socket=192.168.0.1:12345</code> if
    you want to send the output to host IP 192.168.0.1 port 12345 (I
    have no idea if 12345 is a port of pre-existing significance).  You
    can also omit the port number:
    <code class="option">--log-socket=192.168.0.1</code>, in which case a default
    port of 1500 is used.  This default is defined by the constant
    <code class="computeroutput">VG_CLO_DEFAULT_LOGPORT</code> in the
    sources.</p>
<p>Note, unfortunately, that you have to use an IP address here,
    rather than a hostname.</p>
<p>Writing to a network socket is pretty useless if you don't
    have something listening at the other end.  We provide a simple
    listener program,
    <code class="computeroutput">valgrind-listener</code>, which accepts
    connections on the specified port and copies whatever it is sent to
    stdout.  Probably someone will tell us this is a horrible security
    risk.  It seems likely that people will write more sophisticated
    listeners in the fullness of time.</p>
<p>valgrind-listener can accept simultaneous connections from up
    to 50 valgrinded processes.  In front of each line of output it
    prints the current number of active connections in round
    brackets.</p>
<p>valgrind-listener accepts two command-line flags:</p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="option">-e</code> or <code class="option">--exit-at-zero</code>: 
         when the number of connected processes falls back to zero,
         exit.  Without this, it will run forever, that is, until you
         send it Control-C.</p></li>
<li><p><code class="option">portnumber</code>: changes the port it listens
        on from the default (1500).  The specified port must be in the
        range 1024 to 65535.  The same restriction applies to port
        numbers specified by a <code class="option">--log-socket</code> to
        Valgrind itself.</p></li>
</ul></div>
<p>If a valgrinded process fails to connect to a listener, for
    whatever reason (the listener isn't running, invalid or unreachable
    host or port, etc), Valgrind switches back to writing the commentary
    to stderr.  The same goes for any process which loses an established
    connection to a listener.  In other words, killing the listener
    doesn't kill the processes sending data to it.</p>
</li>
</ol></div>
<p>Here is an important point about the relationship between the
commentary and profiling output from tools.  The commentary contains a
mix of messages from the Valgrind core and the selected tool.  If the
tool reports errors, it will report them to the commentary.  However, if
the tool does profiling, the profile data will be written to a file of
some kind, depending on the tool, and independent of what
<code class="option">--log-*</code> options are in force.  The commentary is
intended to be a low-bandwidth, human-readable channel.  Profiling data,
on the other hand, is usually voluminous and not meaningful without
further processing, which is why we have chosen this arrangement.</p>
</div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="manual-core.report"></a>2.4.燫eporting of errors</h2></div></div></div>
<p>When one of the error-checking tools (Memcheck,
Helgrind) detects something bad happening in the program, an error
message is written to the commentary.  For example:</p>
<pre class="programlisting">
==25832== Invalid read of size 4
==25832==    at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45)
==25832==    by 0x80487AF: main (bogon.cpp:66)
==25832==  Address 0xBFFFF74C is not stack'd, malloc'd or free'd</pre>
<p>This message says that the program did an illegal 4-byte read of
address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid
stack address, nor corresponds to any currently malloc'd or free'd
blocks.  The read is happening at line 45 of
<code class="filename">bogon.cpp</code>, called from line 66 of the same file,
etc.  For errors associated with an identified malloc'd/free'd block,
for example reading free'd memory, Valgrind reports not only the
location where the error happened, but also where the associated block
was malloc'd/free'd.</p>
<p>Valgrind remembers all error reports.  When an error is detected,
it is compared against old reports, to see if it is a duplicate.  If so,
the error is noted, but no further commentary is emitted.  This avoids
you being swamped with bazillions of duplicate error reports.</p>
<p>If you want to know how many times each error occurred, run with
the <code class="option">-v</code> option.  When execution finishes, all the
reports are printed out, along with, and sorted by, their occurrence
counts.  This makes it easy to see which errors have occurred most
frequently.</p>
<p>Errors are reported before the associated operation actually
happens.  If you're using a tool (Memcheck) which does
address checking, and your program attempts to read from address zero,
the tool will emit a message to this effect, and the program will then
duly die with a segmentation fault.</p>
<p>In general, you should try and fix errors in the order that they
are reported.  Not doing so can be confusing.  For example, a program
which copies uninitialised values to several memory locations, and later
uses them, will generate several error messages, when run on Memcheck.
The first such error message may well give the most direct clue to the
root cause of the problem.</p>
<p>The process of detecting duplicate errors is quite an
expensive one and can become a significant performance overhead
if your program generates huge quantities of errors.  To avoid
serious problems, Valgrind will simply stop collecting
errors after 1000 different errors have been seen, or 10000000 errors
in total have been seen.  In this situation you might as well
stop your program and fix it, because Valgrind won't tell you
anything else useful after this.  Note that the 1000/10000000 limits
apply after suppressed errors are removed.  These limits are
defined in <code class="filename">m_errormgr.c</code> and can be increased
if necessary.</p>
<p>To avoid this cutoff you can use the
<code class="option">--error-limit=no</code> flag.  Then Valgrind will always show
errors, regardless of how many there are.  Use this flag carefully,
since it may have a bad effect on performance.</p>
</div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="manual-core.suppress"></a>2.5.燬uppressing errors</h2></div></div></div>
<p>The error-checking tools detect numerous problems in the base
libraries, such as the GNU C library, and the XFree86 client libraries,
which come pre-installed on your GNU/Linux system.  You can't easily fix
these, but you don't want to see these errors (and yes, there are many!)
So Valgrind reads a list of errors to suppress at startup.  A default
suppression file is cooked up by the
<code class="computeroutput">./configure</code> script when the system is
built.</p>
<p>You can modify and add to the suppressions file at your leisure,
or, better, write your own.  Multiple suppression files are allowed.
This is useful if part of your project contains errors you can't or
don't want to fix, yet you don't want to continuously be reminded of
them.</p>
<p><b>Note: