docs/xml/FAQ.xml

<?xml version="1.0"?> <!-- -*- sgml -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>


<book id="FAQ" xreflabel="Valgrind FAQ">

<bookinfo>
  <title>Valgrind FAQ</title>
  <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
  <copyright>
    <year>&vg-lifespan;</year>
    <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
  </copyright>
  <author>
    <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
  </author>
</bookinfo>


<article id="faq">
<title>Valgrind Frequently Asked Questions</title>


<!-- FAQ starts here -->
<qandaset>


<!-- Background -->
<qandadiv id="faq.background" xreflabel="Background">
<title>Background</title>

<qandaentry id="faq.pronounce">
 <question id="q-pronounce">
  <para>How do you pronounce "Valgrind"?</para>
 </question>
 <answer id="a-pronounce">
  <para>The "Val" as in the world "value".  The "grind" is
  pronounced with a short 'i' -- ie. "grinned" (rhymes with
  "tinned") rather than "grined" (rhymes with "find").</para>
  <para>Don't feel bad: almost everyone gets it wrong at
  first.</para>
 </answer>
</qandaentry>

<qandaentry id="faq.whence">
 <question id="q-whence">
  <para>Where does the name "Valgrind" come from?</para>
 </question>
 <answer id="a-whence">
  <para>From Nordic mythology.  Originally (before release) the
  project was named Heimdall, after the watchman of the Nordic
  gods.  He could "see a hundred miles by day or night, hear the
  grass growing, see the wool growing on a sheep's back" (etc).
  This would have been a great name, but it was already taken by
  a security package "Heimdal".</para> <para>Keeping with the
  Nordic theme, Valgrind was chosen.  Valgrind is the name of the
  main entrance to Valhalla (the Hall of the Chosen Slain in
  Asgard).  Over this entrance there resides a wolf and over it
  there is the head of a boar and on it perches a huge eagle,
  whose eyes can see to the far regions of the nine worlds.  Only
  those judged worthy by the guardians are allowed to pass
  through Valgrind.  All others are refused entrance.</para>
  <para>It's not short for "value grinder", although that's not a
  bad guess.</para>
  </answer>
 </qandaentry>

</qandadiv>



<!-- Compiling, Installing and Configuring -->
<qandadiv id="faq.installing" xreflabel="Compiling, installing and configuring">
<title>Compiling, installing and configuring</title>

<qandaentry id="faq.make_dies">
 <question id="q-make_dies">
  <para>When I trying building Valgrind, 'make' dies partway with
  an assertion failure, something like this:</para>
<screen>
% make: expand.c:489: allocated_variable_append: 
        Assertion 'current_variable_set_list->next != 0' failed.
</screen>
 </question>
 <answer id="a-make_dies">
  <para>It's probably a bug in 'make'.  Some, but not all,
  instances of version 3.79.1 have this bug, see
  www.mail-archive.com/bug-make@gnu.org/msg01658.html.  Try
  upgrading to a more recent version of 'make'.  Alternatively,
  we have heard that unsetting the CFLAGS environment variable
  avoids the problem.</para>
 </answer>
</qandaentry>

</qandadiv>



<!-- Valgrind aborts unexpectedly -->
<qandadiv id="faq.abort" xreflabel="Valgrind aborts unexpectedly">
<title>Valgrind aborts unexpectedly</title>

<qandaentry id="faq.exit_errors">
 <question id="q-exit_errors">
  <para>Programs run OK on Valgrind, but at exit produce a bunch
  of errors involving <literal>__libc_freeres()</literal>
  and then die with a segmentation fault.</para>
 </question>
 <answer id="a-exit_errors">
  <para>When the program exits, Valgrind runs the procedure
  <literal>__libc_freeres()</literal> in glibc.  This is a hook
  for memory debuggers, so they can ask glibc to free up any
  memory it has used.  Doing that is needed to ensure that
  Valgrind doesn't incorrectly report space leaks in glibc.</para>
  <para>Problem is that running
  <literal>__libc_freeres()</literal> in older glibc versions
  causes this crash.</para> <para>WORKAROUND FOR 1.1.X and later
  versions of Valgrind: use the
  <literal>--run-libc-freeres=no</literal> flag.  You may then get
  space leak reports for glibc-allocations (please _don't_ report
  these to the glibc people, since they are not real leaks), but
  at least the program runs.</para>
 </answer>
</qandaentry>

<qandaentry id="faq.bugdeath">
 <question id="q-bugdeath">
  <para>My (buggy) program dies like this:</para>
<screen>% valgrind: vg_malloc2.c:442 (bszW_to_pszW): Assertion 'pszW >= 0' failed.</screen>
 </question>
 <answer id="a-bugdeath">
  <para>If Memcheck (the memory checker) shows any invalid reads,
  invalid writes and invalid frees in your program, the above may
  happen.  Reason is that your program may trash Valgrind's
  low-level memory manager, which then dies with the above
  assertion, or something like this.  The cure is to fix your
  program so that it doesn't do any illegal memory accesses.  The
  above failure will hopefully go away after that.</para>
 </answer>
</qandaentry>

<qandaentry id="faq.msgdeath">
 <question id="q-msgdeath">
  <para>My program dies, printing a message like this along the
    way:</para>
<screen>% disInstr: unhandled instruction bytes: 0x66 0xF 0x2E 0x5</screen>
 </question>
 <answer id="a-msgdeath">
  <para>Older versions did not support some x86 instructions,
  particularly SSE/SSE2 instructions.  Try a newer Valgrind; we
  now support almost all instructions.  If it still happens with
  newer versions, if the failing instruction is an SSE/SSE2
  instruction, you might be able to recompile your program
  without it by using the flag
  <computeroutput>-march</computeroutput> to gcc.  Either way,
  let us know and we'll try to fix it.</para>

  <para>Another possibility is that your program has a bug and
  erroneously jumps to a non-code address, in which case you'll
  get a SIGILL signal.  Memcheck/Addrcheck may issue a warning
  just before this happens, but they might not if the jump
  happens to land in addressable memory.</para>
 </answer>
</qandaentry>

<qandaentry id="faq.java">
 <question id="q-java">
  <para>I tried running a Java program (or another program that uses a
  just-in-time compiler) under Valgrind but something went wrong.
  Does Valgrind handle such programs?</para>
 </question>
 <answer id="a-java">
  <para>Valgrind can handle dynamically generated code, so long as none
  of the generated code is later overwritten by other generated code.
  If this happens, though, things will go wrong as Valgrind will continue
  running its translations of the old code (this is true on x86 and AMD64,
  on PPC32 there are explicit cache flush instructions which Valgrind
  detects).  You should try running with
  <computeroutput>--smc-check=all</computeroutput> in this case;  Valgrind
  will run much more slowly, but should detect the use of the out-of-date
  code.</para>
  <para>Alternativaly, if you have the source code to the JIT compiler you
  can insert calls to the
  <computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput> client
  request to mark out-of-date code, saving you from using
  <computeroutput>--smc-check=all</computeroutput>.</para>
  <para>Apart from this, in theory Valgrind can run any Java program just
  fine, even those that use JNI and are partially implemented in other
  languages like C and C++.  In practice, Java implementations tend to do
  nasty things that most programs do not, and Valgrind sometimes falls
  over these corner cases.</para>
  <para>If your Java programs do not run under Valgrind, even with
  <computeroutput>--smc-check=all</computeroutput>, please file a bug
  report and hopefully we'll be able to fix the problem.</para>
 </answer>
</qandaentry>

</qandadiv>


<!-- Valgrind behaves unexpectedly -->
<qandadiv id="faq.unexpected" xreflabel="Valgrind behaves unexpectedly">
<title>Valgrind behaves unexpectedly</title>

<qandaentry id="faq.reports">
 <question id="q-reports">
  <para>My program uses the C++ STL and string classes.  Valgrind
  reports 'still reachable' memory leaks involving these classes
  at the exit of the program, but there should be none.</para>
 </question>
 <answer id="a-reports">
  <para>First of all: relax, it's probably not a bug, but a
  feature.  Many implementations of the C++ standard libraries
  use their own memory pool allocators.  Memory for quite a
  number of destructed objects is not immediately freed and given
  back to the OS, but kept in the pool(s) for later re-use.  The
  fact that the pools are not freed at the exit() of the program
  cause Valgrind to report this memory as still reachable.  The
  behaviour not to free pools at the exit() could be called a bug
  of the library though.</para>

  <para>Using gcc, you can force the STL to use malloc and to
  free memory as soon as possible by globally disabling memory
  caching.  Beware!  Doing so will probably slow down your
  program, sometimes drastically.</para>
  <itemizedlist>
   <listitem>
    <para>With gcc 2.91, 2.95, 3.0 and 3.1, compile all source
    using the STL with <literal>-D__USE_MALLOC</literal>. Beware!
    This is removed from gcc starting with version 3.3.</para>
   </listitem>
   <listitem>
    <para>With gcc 3.2.2 and later, you should export the environment
    variable <literal>GLIBCPP_FORCE_NEW</literal> before running
    your program.</para>
   </listitem>
   <listitem>
    <para>With gcc 3.4 and later, that variable has changed name to
    <literal>GLIBCXX_FORCE_NEW</literal>.</para>
   </listitem>
  </itemizedlist>

  <para>There are other ways to disable memory pooling: using the
  <literal>malloc_alloc</literal> template with your objects (not
  portable, but should work for gcc) or even writing your own
  memory allocators. But all this goes beyond the scope of this
  FAQ.  Start by reading <ulink
  url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3">
  http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3</ulink>
  if you absolutely want to do that. But beware:</para>

  <orderedlist>
   <listitem>
    <para>there are currently changes underway for gcc which are
    not totally reflected in the docs right now ("now" == 26 Apr
    03)</para>
   </listitem>
   <listitem>
    <para>allocators belong to the more messy parts of the STL
    and people went to great lengths to make it portable across
    platforms. Chances are good that your solution will work on
    your platform, but not on others.</para>
   </listitem>
  </orderedlist>
 </answer>
</qandaentry>


<qandaentry id="faq.unhelpful">
 <question id="q-unhelpful">
  <para>The stack traces given by Memcheck (or another tool)
  aren't helpful.  How can I improve them?</para>
 </question>
 <answer id="a-unhelpful">
  <para>If they're not long enough, use
  <literal>--num-callers</literal> to make them longer.</para>
  <para>If they're not detailed enough, make sure you are
  compiling with <literal>-g</literal> to add debug information.
  And don't strip symbol tables (programs should be unstripped
  unless you run 'strip' on them; some libraries ship
  stripped).</para>

  <para>Also, for leak reports involving shared objects, if the shared
  object is unloaded before the program terminates, Valgrind will discard
  the debug information and the error message will be full of
  <literal>???</literal> entries.  The workaround here is to avoid calling
  dlclose() on these shared objects.
  </para>

  <para>Also, <literal>-fomit-frame-pointer</literal> and
  <literal>-fstack-check</literal> can make stack traces
  worse.</para>

  <para>Some example sub-traces:</para>

   <itemizedlist>
     <listitem>
       <para>With debug information and unstripped (best):</para>
<programlisting>
Invalid write of size 1
   at 0x80483BF: really (malloc1.c:20)
   by 0x8048370: main (malloc1.c:9)
</programlisting>
     </listitem>

     <listitem>
       <para>With no debug information, unstripped:</para>
<programlisting>
Invalid write of size 1
   at 0x80483BF: really (in /auto/homes/njn25/grind/head5/a.out)
   by 0x8048370: main (in /auto/homes/njn25/grind/head5/a.out)
</programlisting>
     </listitem>

     <listitem>
       <para>With no debug information, stripped:</para>
<programlisting>
Invalid write of size 1
   at 0x80483BF: (within /auto/homes/njn25/grind/head5/a.out)
   by 0x8048370: (within /auto/homes/njn25/grind/head5/a.out)
   by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
   by 0x80482CC: (within /auto/homes/njn25/grind/head5/a.out)
</programlisting>
     </listitem>

     <listitem>
       <para>With debug information and -fomit-frame-pointer:</para>
<programlisting>
Invalid write of size 1
   at 0x80483C4: really (malloc1.c:20)
   by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
   by 0x80482CC: ??? (start.S:81)
</programlisting>
     </listitem>

     <listitem>
      <para>A leak error message involving an unloaded shared object:</para>
<programlisting>
84 bytes in 1 blocks are possibly lost in loss record 488 of 713
   at 0x1B9036DA: operator new(unsigned) (vg_replace_malloc.c:132)
   by 0x1DB63EEB: ???
   by 0x1DB4B800: ???
   by 0x1D65E007: ???
   by 0x8049EE6: main (main.cpp:24)
</programlisting>
     </listitem>
   </itemizedlist>

 </answer>
</qandaentry>

<qandaentry id="faq.aliases">
 <question id="q-aliases">
  <para>The stack traces given by Memcheck (or another tool) seem to
  have the wrong function name in them.  What's happening?</para>
 </question>
 <answer id="a-aliases">
  <para>Occasionally Valgrind stack traces get the wrong function names.
  This is caused by glibc using aliases to effectively give one function two
  names.  Most of the time Valgrind chooses a suitable name, but very
  occasionally it gets it wrong.
  Examples we know of are printing 'bcmp' instead of 'memcmp', 'index'
  instead of 'strchr', and 'rindex' instead of 'strrchr'.</para>
 </answer>
</qandaentry>

</qandadiv>



<!-- Memcheck doesn't find my bug -->
<qandadiv id="faq.notfound" xreflabel="Memcheck doesn't find my bug">
<title>Memcheck doesn't find my bug</title>

<qandaentry id="faq.hiddenbug">
 <question id="q-hiddenbug">
  <para>I try running "valgrind --tool=memcheck my_program" and
  get Valgrind's startup message, but I don't get any errors and
  I know my program has errors.</para>
 </question>
 <answer id="a-hiddenbug">
  <para>There are two possible causes of this.</para>

  <para>First, by default, Valgrind only traces the top-level process.
  So if your program spawns children, they won't be traced by
  Valgrind by default.  Also, if your program is started by a
  shell script, Perl script, or something similar, Valgrind will
  trace the shell, or the Perl interpreter, or equivalent.</para>

  <para>To trace child processes, use the
  <literal>--trace-children=yes</literal> option.</para>

  <para>If you are tracing large trees of processes, it can be
  less disruptive to have the output sent over the network.  Give
  Valgrind the flag
  <literal>--log-socket=127.0.0.1:12345</literal> (if you want
  logging output sent to <literal>port 12345</literal> on
  <literal>localhost</literal>).  You can use the
  valgrind-listener program to listen on that port:</para>
<programlisting>
valgrind-listener 12345
</programlisting>

  <para>Obviously you have to start the listener process first.
  See the manual for more details.</para>

  <para>Second, if your program is statically linked, most Valgrind tools
  won't work as well, because they won't be able to replace certain
  functions, such as malloc(), with their own versions.  A key indicator of
  this is if Memcheck says:
<programlisting>
No malloc'd blocks -- no leaks are possible
</programlisting>
when you know your program calls malloc().  The workaround is to avoid
statically linking your program.</para>
 </answer>
</qandaentry>


<qandaentry id="faq.overruns">
 <question id="q-overruns">
  <para>Why doesn't Memcheck find the array overruns in this program?</para>
<programlisting>
int static[5];

int main(void)
{
  int stack[5];

  static[5] = 0;
  stack [5] = 0;
          
  return 0;
}
</programlisting>
 </question>
 <answer id="a-overruns">
  <para>Unfortunately, Memcheck doesn't do bounds checking on
  static or stack arrays.  We'd like to, but it's just not
  possible to do in a reasonable way that fits with how Memcheck
  works.  Sorry.</para>
 </answer>
</qandaentry>

</qandadiv>



<!-- Miscellaneous -->
<qandadiv id="faq.misc" xreflabel="Miscellaneous">
<title>Miscellaneous</title>

<qandaentry id="faq.writesupp">
 <question id="q-writesupp">
  <para>I tried writing a suppression but it didn't work.  Can
  you write my suppression for me?</para>
 </question>
 <answer id="a-writesupp">
  <para>Yes!  Use the
  <computeroutput>--gen-suppressions=yes</computeroutput> feature
  to spit out suppressions automatically for you.  You can then
  edit them if you like, eg.  combining similar automatically
  generated suppressions using wildcards like
  <literal>'*'</literal>.</para>

  <para>If you really want to write suppressions by hand, read
  the manual carefully.  Note particularly that C++ function
  names must be <literal>_mangled_</literal>.</para>
 </answer>
</qandaentry>


<qandaentry id="faq.deflost">
 <question id="q=deflost">
  <para>With Memcheck/Addrcheck's memory leak detector, what's
  the difference between "definitely lost", "possibly lost",
  "still reachable", and "suppressed"?</para>
 </question>
 <answer id="a-deflost">
  <para>The details are in the Memcheck section of the user manual.</para>

  <para>In short:</para>
   <itemizedlist>
    <listitem>
     <para>"definitely lost" means your program is leaking memory
     -- fix it!</para>
    </listitem>
    <listitem>
     <para>"possibly lost" means your program is probably leaking
     memory, unless you're doing funny things with
     pointers.</para>
    </listitem>
    <listitem>
     <para>"still reachable" means your program is probably ok --
     it didn't free some memory it could have.  This is quite
     common and often reasonable.  Don't use
     <computeroutput>--show-reachable=yes</computeroutput> if you
     don't want to see these reports.</para>
    </listitem>
    <listitem>
     <para>"suppressed" means that a leak error has been
     suppressed.  There are some suppressions in the default
     suppression files.  You can ignore suppressed errors.</para>
    </listitem>
   </itemizedlist>
 </answer>
</qandaentry>

</qandadiv>



<!-- Further Assistance -->
<qandadiv id="faq.help" xreflabel="How To Get Further Assistance">
<title>How To Get Further Assistance</title>

<qandaentry id="e-help">

 <answer id="a-help">
  <para>Please read all of this section before posting.</para>

  <para>If you think an answer is incomplete or inaccurate, please
  e-mail <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink>.</para>
<!--
  <para>Read the appropriate section(s) of the <xref linkend="set-index"/>.</para>
-->
  <para>Read the appropriate section(s) of the 
  <ulink url="&vg-bookset;">Valgrind Documentation</ulink>.</para>

<!--
  <para>Read the <xref linkend="dist"/>.</para>
-->
  <para>Read the 
  <ulink url="&vg-dist-docs;">Distribution Documents</ulink>.</para>

  <para><ulink url="http://search.gmane.org">Search</ulink> the 
  <ulink url="http://news.gmane.org/gmane.comp.debugging.valgrind">valgrind-users</ulink> mailing list archives, using the group name 
  <computeroutput>gmane.comp.debugging.valgrind</computeroutput>.</para>

  <para>Only when you have tried all of these things and are still stuck,
  should you post to the <ulink url="&vg-users-list;">valgrind-users
  mailing list</ulink>. In which case, please read the following
  carefully.  Making a complete posting will greatly increase the chances
  that an expert or fellow user reading it will have enough information
  and motivation to reply.</para>

  <para>Make sure you give full details of the problem,
  including the full output of <computeroutput>valgrind -v</computeroutput>, 
  if applicable.  Also which Linux distribution you're using (Red Hat, Debian, etc) 
  and its version number.</para>

  <para>You are in little danger of making your posting too long
  unless you include large chunks of valgrind's (unsuppressed)
  output, so err on the side of giving too much information.</para>

  <para>Clearly written subject lines and message bodies are appreciated,
  too.</para>

  <para>Finally, remember that, despite the fact that most of the
  community are very helpful and responsive to emailed questions,
  you are probably requesting help from unpaid volunteers, so you
  have no guarantee of receiving an answer.</para>
</answer>

</qandaentry>
</qandadiv>


<!-- FAQ ends here -->
</qandaset>



<!-- template 
<qandadiv id="faq.installing" xreflabel="Installing">
<title>Installing</title>

<qandaentry id="faq.problem">
 <question id="q-problem">
  <para></para>
 </question>
 <answer id="a-problem">
  <para></para>
 </answer>
</qandaentry>

</qandadiv>
-->

</article>

</book>