Overhauled the docs. Removed all the HTML files, put in XML files as
converted by Donna. Hooked it into the build system so they are only
built when specifically asked for, and when doing "make dist".
They're not perfect; in particular, there are the following problems:
- The plain-text FAQ should be built from FAQ.xml, but this is not
currently done. (The text FAQ has been left in for now.)
- The PS/PDF building doesn't work -- it fails with an incomprehensible
error message which I haven't yet deciphered.
Nonetheless, I'm putting it in so others can see it.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@3153 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
new file mode 100644
index 0000000..96897d6
--- /dev/null
+++ b/docs/xml/FAQ.xml
@@ -0,0 +1,674 @@
+<?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>
+ </bookinfo>
+
+
+<chapter id="faq.background" xreflabel="Background">
+<title>Background</title>
+
+<qandaset id="qset.background">
+
+<qandaentry id="faq.pronounce">
+ <question>
+ <para>How do you pronounce "Valgrind"?</para>
+ </question>
+ <answer>
+ <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>
+ <para>Where does the name "Valgrind" come from?</para>
+ </question>
+ <answer>
+ <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>
+
+</qandaset>
+
+</chapter>
+
+
+<chapter id="faq.installing"
+ xreflabel="Compiling, installing and configuring">
+<title>Compiling, installing and configuring</title>
+<qandaset id="qset.installing">
+
+<qandaentry id="faq.make_dies">
+ <question>
+ <para>When I trying building Valgrind, 'make' dies partway with
+ an assertion failure, something like this:
+<screen>
+% make: expand.c:489: allocated_variable_append:
+ Assertion 'current_variable_set_list->next != 0' failed.
+</screen>
+ </para>
+ </question>
+ <answer>
+ <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>
+
+</qandaset>
+</chapter>
+
+
+
+<chapter id="faq.abort"
+ xreflabel="Valgrind aborts unexpectedly">
+<title>Valgrind aborts unexpectedly</title>
+<qandaset id="qset.abort">
+
+<qandaentry id="faq.exit_errors">
+ <question>
+ <para>Programs run OK on Valgrind, but at exit produce a bunch
+ of errors a bit like this:</para>
+ </question>
+ <answer><para>
+<programlisting>
+==20755== Invalid read of size 4
+==20755== at 0x40281C8A: _nl_unload_locale (loadlocale.c:238)
+==20755== by 0x4028179D: free_mem (findlocale.c:257)
+==20755== by 0x402E0962: __libc_freeres (set-freeres.c:34)
+==20755== by 0x40048DCC: vgPlain___libc_freeres_wrapper (vg_clientfuncs.c:585)
+==20755== Address 0x40CC304C is 8 bytes inside a block of size 380 free'd
+==20755== at 0x400484C9: free (vg_clientfuncs.c:180)
+==20755== by 0x40281CBA: _nl_unload_locale (loadlocale.c:246)
+==20755== by 0x40281218: free_mem (setlocale.c:461)
+==20755== by 0x402E0962: __libc_freeres (set-freeres.c:34)
+</programlisting>
+
+ and then die with a segmentation fault.</para>
+ <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>
+ <para>My (buggy) program dies like this:</para>
+ </question>
+ <answer>
+ <screen>
+% valgrind: vg_malloc2.c:442 (bszW_to_pszW): Assertion 'pszW >= 0' failed.
+</screen>
+
+ <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>
+ <para>My program dies, printing a message like this along the
+ way:</para>
+ </question>
+ <answer>
+<screen>
+% disInstr: unhandled instruction bytes: 0x66 0xF 0x2E 0x5
+</screen>
+
+ <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 progrma
+ 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.defdeath">
+ <question>
+ <para>My program dies like this:</para>
+ </question>
+ <answer>
+<screen>
+% error: /lib/librt.so.1: symbol __pthread_clock_settime,
+ version GLIBC_PRIVATE not defined in file libpthread.so.0 with link time reference
+</screen>
+
+ <para>This is a total swamp. Nevertheless there is a way out.
+ It's a problem which is not easy to fix. Really the problem is
+ that <filename>/lib/librt.so.1</filename> refers to some
+ symbols <literal>__pthread_clock_settime</literal> and
+ <literal>__pthread_clock_gettime</literal> in
+ <filename>/lib/libpthread.so</filename> which are not intended
+ to be exported, ie they are private.</para>
+
+ <para>Best solution is to ensure your program does not use
+ <filename>/lib/librt.so.1</filename>.</para>
+
+ <para>However ... since you're probably not using it directly,
+ or even knowingly, that's hard to do. You might instead be
+ able to fix it by playing around with
+ <filename>coregrind/vg_libpthread.vs</filename>. Things to
+ try:</para>
+
+ <para>Remove this:</para>
+<programlisting>
+GLIBC_PRIVATE {
+ __pthread_clock_gettime;
+ __pthread_clock_settime;
+};
+</programlisting>
+
+<para>or maybe remove this</para>
+<programlisting>
+GLIBC_2.2.3 {
+ __pthread_clock_gettime;
+ __pthread_clock_settime;
+} GLIBC_2.2;
+</programlisting>
+
+<para>or maybe add this:</para>
+<programlisting>
+GLIBC_2.2.4 {
+ __pthread_clock_gettime;
+ __pthread_clock_settime;
+} GLIBC_2.2;
+
+GLIBC_2.2.5 {
+ __pthread_clock_gettime;
+ __pthread_clock_settime;
+} GLIBC_2.2;
+</programlisting>
+
+ <para>or some combination of the above. After each change you
+ need to delete <filename>coregrind/libpthread.so</filename> and
+ do <computeroutput>make && make
+ install</computeroutput>.</para>
+
+ <para>I just don't know if any of the above will work. If you
+ can find a solution which works, I would be interested to hear
+ it.</para>
+
+ <para>To which someone replied:</para>
+<screen>
+I deleted this:
+
+GLIBC_2.2.3 {
+ __pthread_clock_gettime;
+ __pthread_clock_settime;
+} GLIBC_2.2;
+
+and it worked.
+</screen>
+
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+<chapter id="faq.unexpected"
+ xreflabel="Valgrind behaves unexpectedly">
+<title>Valgrind behaves unexpectedly</title>
+<qandaset id="qset.unexpected">
+
+<qandaentry id="faq.no-output">
+ <question>
+ <para>I try running "valgrind my-program", but my-program runs
+ normally, and Valgrind doesn't emit any output at all.</para>
+ </question>
+ <answer>
+ <para><command>For versions prior to 2.1.1:</command></para>
+
+ <para>Valgrind doesn't work out-of-the-box with programs that
+ are entirely statically linked. It does a quick test at
+ startup, and if it detects that the program is statically
+ linked, it aborts with an explanation.</para>
+
+ <para>This test may fail in some obscure cases, eg. if you run
+ a script under Valgrind and the script interpreter is
+ statically linked.</para>
+
+ <para>If you still want static linking, you can ask gcc to link
+ certain libraries statically. Try the following options:</para>
+<screen>
+-Wl,-Bstatic -lmyLibrary1 -lotherLibrary -Wl,-Bdynamic
+</screen>
+
+ <para>Just make sure you end with
+ <computeroutput>-Wl,-Bdynamic</computeroutput> so that libc is
+ dynamically linked.</para>
+
+ <para>If you absolutely cannot use dynamic libraries, you can
+ try statically linking together all the .o files in coregrind/,
+ all the .o files of the tool of your choice (eg. those in
+ memcheck/), and the .o files of your program. You'll end up
+ with a statically linked binary that runs permanently under
+ Valgrind's control. Note that we haven't tested this procedure
+ thoroughly.</para>
+
+ <para><command>For versions 2.1.1 and later:</command></para>
+ <para>Valgrind does now work with static binaries, although
+ beware that some of the tools won't operate as well as normal,
+ because they have access to less information about how the
+ program runs. Eg. Memcheck will miss some errors that it would
+ otherwise find. This is because Valgrind doesn't replace
+ malloc() and friends with its own versions. It's best if your
+ program is dynamically linked with glibc.</para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.slowthread">
+ <question>
+ <para>My threaded server process runs unbelievably slowly on
+ Valgrind. So slowly, in fact, that at first I thought it had
+ completely locked up.</para>
+ </question>
+ <answer>
+ <para>We are not completely sure about this, but one
+ possibility is that laptops with power management fool
+ Valgrind's timekeeping mechanism, which is (somewhat in error)
+ based on the x86 RDTSC instruction. A "fix" which is claimed
+ to work is to run some other cpu-intensive process at the same
+ time, so that the laptop's power-management clock-slowing does
+ not kick in. We would be interested in hearing more feedback
+ on this.</para>
+
+ <para>Another possible cause is that versions prior to 1.9.6
+ did not support threading on glibc 2.3.X systems well.
+ Hopefully the situation is much improved with 1.9.6 and later
+ versions.</para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.reports">
+ <question>
+ <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>
+ <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 3.2.2 and later, you should export the environment
+ variable <literal>GLIBCPP_FORCE_NEW</literal> before running
+ your program.</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 at 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>
+ <para>The stack traces given by Memcheck (or another tool)
+ aren't helpful. How can I improve them?</para>
+ </question>
+ <answer>
+ <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, <literal>-fomit-frame-pointer</literal> and
+ <literal>-fstack-check</literal> can make stack traces
+ worse.</para>
+
+ <para>Some example sub-traces:</para>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+<chapter id="faq.notfound" xreflabel="Memcheck doesn't find my bug">
+<title>Memcheck doesn't find my bug</title>
+<qandaset id="qset.notfound">
+
+<qandaentry id="faq.hiddenbug">
+ <question>
+ <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>
+ <para>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: <ulink url="http://www.valgrind.org/docs/bookset/manual-core.out2file.html">Directing output to file</ulink> for more details.</para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.overruns">
+ <question>
+ <para>Why doesn't Memcheck find the array overruns in this program?</para>
+ </question>
+ <answer>
+<programlisting>
+int static[5];
+
+int main(void)
+{
+ int stack[5];
+
+ static[5] = 0;
+ stack [5] = 0;
+
+ return 0;
+}
+</programlisting>
+ <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>
+
+
+<qandaentry id="faq.segfault">
+ <question>
+ <para>My program dies with a segmentation fault, but Memcheck
+ doesn't give any error messages before it, or none that look
+ related.</para>
+ </question>
+ <answer>
+ <para>One possibility is that your program accesses to memory
+ with inappropriate permissions set, such as writing to
+ read-only memory. Maybe your program is writing to a static
+ string like this:</para>
+<programlisting>
+char* s = "hello";
+s[0] = 'j';
+</programlisting>
+
+ <para>or something similar. Writing to read-only memory can
+ also apparently make LinuxThreads behave strangely.</para>
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+<chapter id="faq.misc"
+ xreflabel="Miscellaneous">
+<title>Miscellaneous</title>
+<qandaset id="qset.misc">
+
+<qandaentry id="faq.writesupp">
+ <question>
+ <para>I tried writing a suppression but it didn't work. Can
+ you write my suppression for me?</para>
+ </question>
+ <answer>
+ <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>
+ <para>With Memcheck/Addrcheck's memory leak detector, what's
+ the difference between "definitely lost", "possibly lost",
+ "still reachable", and "suppressed"?</para>
+ </question>
+ <answer>
+ <para>The details are in the Manual:
+ <ulink url="http://www.valgrind.org/docs/bookset/mc-manual.leaks.html">Memory leak detection</ulink>.</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>
+
+
+</qandaset>
+</chapter>
+
+
+<!-- template
+<chapter id="faq."
+ xreflabel="xx">
+<title>xx</title>
+<qandaset id="qset.">
+
+<qandaentry id="faq.deflost">
+ <question>
+ <para></para>
+ </question>
+ <answer>
+ <para></para>
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+-->
+
+
+
+<chapter id="faq.help" xreflabel="How To Get Further Assistance">
+<title>How To Get Further Assistance</title>
+
+
+<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 Manual(s):
+<ulink url="http://www.valgrind.org/docs/">Valgrind
+Documentation</ulink>.</para>
+
+<para>Read the <ulink url="http://www.valgrind.org/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>
+
+</chapter>
+
+</book>
diff --git a/docs/xml/Makefile.am b/docs/xml/Makefile.am
new file mode 100644
index 0000000..c07286e
--- /dev/null
+++ b/docs/xml/Makefile.am
@@ -0,0 +1,10 @@
+EXTRA_DIST = \
+ index.xml \
+ FAQ.xml \
+ manual.xml manual-intro.xml manual-core.xml \
+ writing-tools.xml \
+ dist-docs.xml \
+ tech-docs.xml \
+ licenses.xml \
+ vg-entities.xml \
+ xml_help.txt
diff --git a/docs/xml/dist-docs.xml b/docs/xml/dist-docs.xml
new file mode 100644
index 0000000..6fb0244
--- /dev/null
+++ b/docs/xml/dist-docs.xml
@@ -0,0 +1,82 @@
+<?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">
+
+<book id="dist" xreflabel="Distribution Documents">
+
+ <bookinfo>
+ <title>Distribution Documents</title>
+ </bookinfo>
+
+ <!-- Nb: because these are all text files, we have to wrap them in suitable
+ XML. Hence the chapter/title stuff -->
+
+ <chapter id="dist.acknowledge" xreflabel="Acknowledgements">
+ <title>ACKNOWLEDGEMENTS</title>
+ <literallayout>
+ <xi:include href="../../ACKNOWLEDGEMENTS" parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="dist.authors" xreflabel="Valgrind Developers">
+ <title id="dist.authors.title">AUTHORS</title>
+ <literallayout>
+ <xi:include href="../../AUTHORS" parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="dist.install" xreflabel="Install">
+ <title>INSTALL</title>
+ <literallayout>
+ <xi:include href="../../INSTALL" parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="dist.news" xreflabel="News">
+ <title>NEWS</title>
+ <literallayout>
+ <xi:include href="../../NEWS" parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="dist.readme" xreflabel="Readme">
+ <title>README</title>
+ <literallayout>
+ <xi:include href="../../README" parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="dist.readme-missing"
+ xreflabel="Readme Missing Syscall or Ioctl">
+ <title>README_MISSING_SYSCALL_OR_IOCTL</title>
+ <literallayout>
+ <xi:include href="../../README_MISSING_SYSCALL_OR_IOCTL"
+ parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="dist.readme-packagers"
+ xreflabel="Readme Packagers">
+ <title>README_PACKAGERS</title>
+ <literallayout>
+ <xi:include href="../../README_PACKAGERS"
+ parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="dist.todo" xreflabel="Todo">
+ <title>TODO</title>
+ <literallayout>
+ <xi:include href="../../TODO"
+ parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+</book>
diff --git a/docs/xml/index.xml b/docs/xml/index.xml
new file mode 100644
index 0000000..97d7231
--- /dev/null
+++ b/docs/xml/index.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[
+ <!-- various strings, dates etc. common to all docs -->
+ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities;
+]>
+
+<set lang="en" id="index">
+
+ <setinfo>
+ <title>Valgrind Documentation</title>
+ <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
+ <copyright>
+ <year>&vg-lifespan;</year>
+ <holder>
+ <link linkend="dist.authors" endterm="dist.authors.title"></link>
+ </holder>
+ </copyright>
+
+ <legalnotice>
+ <para>Permission is granted to copy, distribute and/or
+ modify this document under the terms of the GNU Free
+ Documentation License, Version 1.2 or any later version
+ published by the Free Software Foundation; with no
+ Invariant Sections, with no Front-Cover Texts, and with no
+ Back-Cover Texts. A copy of the license is included in the
+ section entitled <xref linkend="license.gfdl"/>.</para>
+ </legalnotice>
+
+ </setinfo>
+
+ <!-- User Manual -->
+ <xi:include href="manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <!-- FAQ -->
+ <xi:include href="FAQ.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <!-- Technical Docs -->
+ <xi:include href="tech-docs.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <!-- Distribution Docs -->
+ <xi:include href="dist-docs.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <!-- GNU Licenses -->
+ <xi:include href="licenses.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+</set>
diff --git a/docs/xml/licenses.xml b/docs/xml/licenses.xml
new file mode 100644
index 0000000..2b31e9a
--- /dev/null
+++ b/docs/xml/licenses.xml
@@ -0,0 +1,29 @@
+<?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">
+
+<book id="licenses" xreflabel="GNU Licenses">
+
+ <bookinfo>
+ <title>GNU Licenses</title>
+ </bookinfo>
+
+ <chapter id="license.gpl" xreflabel=" The GNU General Public License">
+ <title>The GNU General Public License</title>
+ <literallayout>
+ <xi:include href="../../COPYING"
+ parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+ <chapter id="license.gfdl" xreflabel="The GNU Free Documentation License">
+ <title>The GNU Free Documentation License</title>
+ <literallayout>
+ <xi:include href="../../COPYING.DOCS"
+ parse="text"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </literallayout>
+ </chapter>
+
+</book>
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
new file mode 100644
index 0000000..6ed8eea
--- /dev/null
+++ b/docs/xml/manual-core.xml
@@ -0,0 +1,1951 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="manual-core" xreflabel="Valgrind's core">
+<title>Using and understanding the Valgrind core</title>
+
+<para>This section describes the Valgrind core services, flags
+and behaviours. That means it is relevant regardless of what
+particular tool you are using. A point of terminology: most
+references to "valgrind" in the rest of this section (Section 2)
+refer to the valgrind core services.</para>
+
+<sect1 id="manual-core.whatdoes"
+ xreflabel="What Valgrind does with your program">
+<title>What Valgrind does with your program</title>
+
+<para>Valgrind is designed to be as non-intrusive as possible. It
+works directly with existing executables. You don't need to
+recompile, relink, or otherwise modify, the program to be
+checked.</para>
+
+<para>Simply put <computeroutput>valgrind
+--tool=tool_name</computeroutput> at the start of the command
+line normally used to run the program. For example, if want to
+run the command <computeroutput>ls -l</computeroutput> using the
+heavyweight memory-checking tool Memcheck, issue the
+command:</para>
+
+<programlisting><![CDATA[
+valgrind --tool=memcheck ls -l]]></programlisting>
+
+<para>Regardless of which tool is in use, Valgrind takes control
+of your program before it starts. Debugging information is read
+from the executable and associated libraries, so that error
+messages and other outputs can be phrased in terms of source code
+locations (if that is appropriate).</para>
+
+<para>Your program is then run on a synthetic x86 CPU provided by
+the Valgrind core. As new code is executed for the first time,
+the core hands the code to the selected tool. The tool adds its
+own instrumentation code to this and hands the result back to the
+core, which coordinates the continued execution of this
+instrumented code.</para>
+
+<para>The amount of instrumentation code added varies widely
+between tools. At one end of the scale, Memcheck adds code to
+check every memory access and every value computed, increasing
+the size of the code at least 12 times, and making it run 25-50
+times slower than natively. At the other end of the spectrum,
+the ultra-trivial "none" tool (a.k.a. Nulgrind) adds no
+instrumentation at all and causes in total "only" about a 4 times
+slowdown.</para>
+
+<para>Valgrind simulates every single instruction your program
+executes. Because of this, the active tool checks, or profiles,
+not only the code in your application but also in all supporting
+dynamically-linked (<computeroutput>.so</computeroutput>-format)
+libraries, including the GNU C library, the X client libraries,
+Qt, if you work with KDE, and so on.</para>
+
+<para>If you're using one of the error-detection tools, Valgrind
+will often detect errors in libraries, for example the GNU C or
+X11 libraries, which you have to use. You might not be
+interested in these errors, since you probably have no control
+over that code. Therefore, Valgrind allows you to selectively
+suppress errors, by recording them in a suppressions file which
+is read when Valgrind starts up. The build mechanism attempts to
+select suppressions which give reasonable behaviour for the libc
+and XFree86 versions detected on your machine. To make it easier
+to write suppressions, you can use the
+<computeroutput>--gen-suppressions=yes</computeroutput> option
+which tells Valgrind to print out a suppression for each error
+that appears, which you can then copy into a suppressions
+file.</para>
+
+<para>Different error-checking tools report different kinds of
+errors. The suppression mechanism therefore allows you to say
+which tool or tool(s) each suppression applies to.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.started" xreflabel="Getting started">
+<title>Getting started</title>
+
+<para>First off, consider whether it might be beneficial to
+recompile your application and supporting libraries with
+debugging info enabled (the <computeroutput>-g</computeroutput>
+flag). Without debugging info, the best Valgrind tools will be
+able to do is guess which function a particular piece of code
+belongs to, which makes both error messages and profiling output
+nearly useless. With <computeroutput>-g</computeroutput>, you'll
+hopefully get messages which point directly to the relevant
+source code lines.</para>
+
+<para>Another flag you might like to consider, if you are working
+with C++, is <computeroutput>-fno-inline</computeroutput>. That
+makes it easier to see the function-call chain, which can help
+reduce confusion when navigating around large C++ apps. For
+whatever it's worth, debugging OpenOffice.org with Memcheck is a
+bit easier when using this flag.</para>
+
+<para>You don't have to do this, but doing so helps Valgrind
+produce more accurate and less confusing error reports. Chances
+are you're set up like this already, if you intended to debug
+your program with GNU gdb, or some other debugger.</para>
+
+<para>This paragraph applies only if you plan to use Memcheck: On
+rare occasions, optimisation levels at
+<computeroutput>-O2</computeroutput> and above have been observed
+to generate code which fools Memcheck into wrongly reporting
+uninitialised value errors. We have looked in detail into fixing
+this, and unfortunately the result is that doing so would give a
+further significant slowdown in what is already a slow tool. So
+the best solution is to turn off optimisation altogether. Since
+this often makes things unmanagably slow, a plausible compromise
+is to use <computeroutput>-O</computeroutput>. This gets you the
+majority of the benefits of higher optimisation levels whilst
+keeping relatively small the chances of false complaints from
+Memcheck. All other tools (as far as we know) are unaffected by
+optimisation level.</para>
+
+<para>Valgrind understands both the older "stabs" debugging
+format, used by gcc versions prior to 3.1, and the newer DWARF2
+format used by gcc 3.1 and later. We continue to refine and
+debug our debug-info readers, although the majority of effort
+will naturally enough go into the newer DWARF2 reader.</para>
+
+<para>When you're ready to roll, just run your application as you
+would normally, but place <computeroutput>valgrind
+--tool=tool_name</computeroutput> in front of your usual
+command-line invocation. Note that you should run the real
+(machine-code) executable here. If your application is started
+by, for example, a shell or perl script, you'll need to modify it
+to invoke Valgrind on the real executables. Running such scripts
+directly under Valgrind will result in you getting error reports
+pertaining to <computeroutput>/bin/sh</computeroutput>,
+<computeroutput>/usr/bin/perl</computeroutput>, or whatever
+interpreter you're using. This may not be what you want and can
+be confusing. You can force the issue by giving the flag
+<computeroutput>--trace-children=yes</computeroutput>, but
+confusion is still likely.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.comment" xreflabel="The commentary">
+<title>The commentary</title>
+
+<para>Valgrind tools write a commentary, a stream of text,
+detailing error reports and other significant events. All lines
+in the commentary have following form:
+
+<programlisting><![CDATA[
+==12345== some-message-from-Valgrind]]></programlisting>
+</para>
+
+<para>The <computeroutput>12345</computeroutput> 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.</para>
+
+<para>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
+<computeroutput>-v</computeroutput> flag to Valgrind.</para>
+
+<para>You can direct the commentary to three different
+places:</para>
+
+<orderedlist>
+
+ <listitem id="manual-core.out2fd" xreflabel="Directing output to fd">
+ <para>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
+ <computeroutput>--log-fd=9</computeroutput>.</para>
+ </listitem>
+
+ <listitem id="manual-core.out2file"
+ xreflabel="Directing output to file">
+ <para>A less intrusive option is to write the commentary to a
+ file, which you specify by
+ <computeroutput>--log-file=filename</computeroutput>. Note
+ carefully that the commentary is <command>not</command>
+ written to the file you specify, but instead to one called
+ <computeroutput>filename.pid12345</computeroutput>, 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.</para>
+ </listitem>
+
+ <listitem id="manual-core.out2socket"
+ xreflabel="Directing output to network socket">
+ <para>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:
+ <computeroutput>--log-socket=192.168.0.1:12345</computeroutput>
+ 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:
+ <computeroutput>--log-socket=192.168.0.1</computeroutput>, in
+ which case a default port of 1500 is used. This default is
+ defined by the constant
+ <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the
+ sources.</para>
+
+ <para>Note, unfortunately, that you have to use an IP address
+ here, rather than a hostname.</para>
+
+ <para>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,
+ <computeroutput>valgrind-listener</computeroutput>, 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.</para>
+
+ <para>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.</para>
+
+ <para>valgrind-listener accepts two command-line flags:</para>
+ <itemizedlist>
+ <listitem>
+ <para><computeroutput>-e</computeroutput> or
+ <computeroutput>--exit-at-zero</computeroutput>: 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.</para>
+ </listitem>
+ <listitem>
+ <para><computeroutput>portnumber</computeroutput>: 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
+ <computeroutput>--log-socket=</computeroutput> to Valgrind
+ itself.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>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.</para>
+ </listitem>
+ </orderedlist>
+
+<para>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
+<computeroutput>--log-*</computeroutput> 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.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.report" xreflabel="Reporting of errors">
+<title>Reporting of errors</title>
+
+<para>When one of the error-checking tools (Memcheck, Addrcheck,
+Helgrind) detects something bad happening in the program, an
+error message is written to the commentary. For example:</para>
+
+<programlisting><![CDATA[
+==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== by 0x40371E5E: __libc_start_main (libc-start.c:129)
+==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon)
+==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]></programlisting>
+
+<para>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
+<filename>bogon.cpp</filename>, 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.</para>
+
+<para>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.</para>
+
+<para>If you want to know how many times each error occurred, run
+with the <computeroutput>-v</computeroutput> 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.</para>
+
+<para>Errors are reported before the associated operation
+actually happens. If you're using a tool (Memcheck, Addrcheck)
+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.</para>
+
+<para>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.</para>
+
+<para>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 here, Valgrind will simply stop collecting
+errors after 300 different errors have been seen, or 30000 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 300/30000 limits
+apply after suppressed errors are removed. These limits are
+defined in <filename>vg_include.h</filename> and can be increased
+if necessary.</para>
+
+<para>To avoid this cutoff you can use the
+<computeroutput>--error-limit=no</computeroutput> flag. Then
+Valgrind will always show errors, regardless of how many there
+are. Use this flag carefully, since it may have a dire effect on
+performance.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.suppress" xreflabel="Suppressing errors">
+<title>Suppressing errors</title>
+
+<para>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 <computeroutput>./configure</computeroutput>
+script when the system is built.</para>
+
+<para>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.</para>
+
+<formalpara><title>Note:</title>
+<para>By far the easiest way to add suppressions is to use the
+<computeroutput>--gen-suppressions=yes</computeroutput> flag
+described in <xref linkend="manual-core.flags"/>.</para>
+</formalpara>
+
+<para>Each error to be suppressed is described very specifically,
+to minimise the possibility that a suppression-directive
+inadvertantly suppresses a bunch of similar errors which you did
+want to see. The suppression mechanism is designed to allow
+precise yet flexible specification of errors to suppress.</para>
+
+<para>If you use the <computeroutput>-v</computeroutput> flag, at
+the end of execution, Valgrind prints out one line for each used
+suppression, giving its name and the number of times it got used.
+Here's the suppressions used by a run of <computeroutput>valgrind
+--tool=memcheck ls -l</computeroutput>:</para>
+
+<programlisting><![CDATA[
+--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r
+--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r
+--27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object]]></programlisting>
+
+<para>Multiple suppressions files are allowed. By default,
+Valgrind uses
+<computeroutput>$PREFIX/lib/valgrind/default.supp</computeroutput>.
+You can ask to add suppressions from another file, by specifying
+<computeroutput>--suppressions=/path/to/file.supp</computeroutput>.
+</para>
+
+<para>If you want to understand more about suppressions, look at
+an existing suppressions file whilst reading the following
+documentation. The file
+<computeroutput>glibc-2.2.supp</computeroutput>, in the source
+distribution, provides some good examples.</para>
+
+<para>Each suppression has the following components:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>First line: its name. This merely gives a handy name to
+ the suppression, by which it is referred to in the summary of
+ used suppressions printed out when a program finishes. It's
+ not important what the name is; any identifying string will
+ do.</para>
+ </listitem>
+
+ <listitem>
+ <para>Second line: name of the tool(s) that the suppression is
+ for (if more than one, comma-separated), and the name of the
+ suppression itself, separated by a colon (Nb: no spaces are
+ allowed), eg:</para>
+
+<programlisting><![CDATA[
+tool_name1,tool_name2:suppression_name]]></programlisting>
+
+ <para>Recall that Valgrind-2.0.X is a modular system, in which
+ different instrumentation tools can observe your program
+ whilst it is running. Since different tools detect different
+ kinds of errors, it is necessary to say which tool(s) the
+ suppression is meaningful to.</para>
+
+ <para>Tools will complain, at startup, if a tool does not
+ understand any suppression directed to it. Tools ignore
+ suppressions which are not directed to them. As a result, it
+ is quite practical to put suppressions for all tools into the
+ same suppression file.</para>
+
+ <para>Valgrind's core can detect certain PThreads API errors,
+ for which this line reads:</para>
+
+<programlisting><![CDATA[
+core:PThread]]></programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Next line: a small number of suppression types have
+ extra information after the second line (eg. the
+ <computeroutput>Param</computeroutput> suppression for
+ Memcheck)</para>
+ </listitem>
+
+ <listitem>
+ <para>Remaining lines: This is the calling context for the
+ error -- the chain of function calls that led to it. There
+ can be up to four of these lines.</para>
+
+ <para>Locations may be either names of shared
+ objects/executables or wildcards matching function names.
+ They begin <computeroutput>obj:</computeroutput> and
+ <computeroutput>fun:</computeroutput> respectively. Function
+ and object names to match against may use the wildcard
+ characters <computeroutput>*</computeroutput> and
+ <computeroutput>?</computeroutput>.</para>
+
+ <formalpara><title>Important note:</title>
+ <para>C++ function names must be <command>mangled</command>.
+ If you are writing suppressions by hand, use the
+ <computeroutput>--demangle=no</computeroutput> option to get
+ the mangled names in your error messages.</para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <para>Finally, the entire suppression must be between curly
+ braces. Each brace must be the first character on its own
+ line.</para>
+ </listitem>
+
+ </itemizedlist>
+
+<para>A suppression only suppresses an error when the error
+matches all the details in the suppression. Here's an
+example:</para>
+
+<programlisting><![CDATA[
+{
+ __gconv_transform_ascii_internal/__mbrtowc/mbtowc
+ Memcheck:Value4
+ fun:__gconv_transform_ascii_internal
+ fun:__mbr*toc
+ fun:mbtowc
+}]]></programlisting>
+
+
+<para>What it means is: for Memcheck only, suppress a
+use-of-uninitialised-value error, when the data size is 4, when
+it occurs in the function
+<computeroutput>__gconv_transform_ascii_internal</computeroutput>,
+when that is called from any function of name matching
+<computeroutput>__mbr*toc</computeroutput>, when that is called
+from <computeroutput>mbtowc</computeroutput>. It doesn't apply
+under any other circumstances. The string by which this
+suppression is identified to the user is
+<computeroutput>__gconv_transform_ascii_internal/__mbrtowc/mbtowc</computeroutput>.</para>
+
+<para>(See <xref linkend="mc-manual.suppfiles"/> for more details
+on the specifics of Memcheck's suppression kinds.)</para>
+
+<para>Another example, again for the Memcheck tool:</para>
+
+<programlisting><![CDATA[
+{
+ libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
+ Memcheck:Value4
+ obj:/usr/X11R6/lib/libX11.so.6.2
+ obj:/usr/X11R6/lib/libX11.so.6.2
+ obj:/usr/X11R6/lib/libXaw.so.7.0
+}]]></programlisting>
+
+<para>Suppress any size 4 uninitialised-value error which occurs
+anywhere in <computeroutput>libX11.so.6.2</computeroutput>, when
+called from anywhere in the same library, when called from
+anywhere in <computeroutput>libXaw.so.7.0</computeroutput>. The
+inexact specification of locations is regrettable, but is about
+all you can hope for, given that the X11 libraries shipped with
+Red Hat 7.2 have had their symbol tables removed.</para>
+
+<para>Note: since the above two examples did not make it clear,
+you can freely mix the <computeroutput>obj:</computeroutput> and
+<computeroutput>fun:</computeroutput> styles of description
+within a single suppression record.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.flags"
+ xreflabel="Command-line flags for the Valgrind core">
+<title>Command-line flags for the Valgrind core</title>
+
+<para>As mentioned above, Valgrind's core accepts a common set of
+flags. The tools also accept tool-specific flags, which are
+documented seperately for each tool.</para>
+
+<para>You invoke Valgrind like this:</para>
+
+<programlisting><![CDATA[
+valgrind --tool=<emphasis>tool_name</emphasis> [valgrind-options] your-prog [your-prog options]]]></programlisting>
+
+<para>Valgrind's default settings succeed in giving reasonable
+behaviour in most cases. We group the available options by rough
+categories.</para>
+
+<sect2 id="manual-core.toolopts" xreflabel="Tool-selection option">
+<title>Tool-selection option</title>
+
+<para>The single most important option.</para>
+ <itemizedlist>
+ <listitem>
+ <para><computeroutput>--tool=name</computeroutput></para>
+ <para>Run the Valgrind tool called <emphasis>name</emphasis>,
+ e.g. Memcheck, Addrcheck, Cachegrind, etc.</para>
+ </listitem>
+ </itemizedlist>
+</sect2>
+
+<sect2 id="manual-core.basicopts" xreflabel="Basic Options">
+<title>Basic Options</title>
+
+<para>These options work with all tools.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><computeroutput>--help</computeroutput></para>
+ <para>Show help for all options, both for the core and for
+ the selected tool.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--help-debug</computeroutput></para>
+ <para>Same as <computeroutput>--help</computeroutput>, but
+ also lists debugging options which usually are only of use
+ to developers.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--version</computeroutput></para>
+ <para>Show the version number of the Valgrind core. Tools
+ can have their own version numbers. There is a scheme in
+ place to ensure that tools only execute when the core version
+ is one they are known to work with. This was done to
+ minimise the chances of strange problems arising from
+ tool-vs-core version incompatibilities.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>-v --verbose</computeroutput></para>
+ <para>Be more verbose. Gives extra information on various
+ aspects of your program, such as: the shared objects loaded,
+ the suppressions used, the progress of the instrumentation
+ and execution engines, and warnings about unusual behaviour.
+ Repeating the flag increases the verbosity level.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>-q --quiet</computeroutput></para>
+ <para>Run silently, and only print error messages. Useful if
+ you are running regression tests or have some other automated
+ test machinery.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-children=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--trace-children=yes</computeroutput></para>
+ <para>When enabled, Valgrind will trace into child processes.
+ This is confusing and usually not what you want, so is
+ disabled by default.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--log-fd=<number></computeroutput>
+ [default: 2, stderr]</para>
+ <para>Specifies that Valgrind should send all of its messages
+ to the specified file descriptor. The default, 2, is the
+ standard error channel (stderr). Note that this may
+ interfere with the client's own use of stderr.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--log-file=<filename></computeroutput></para>
+ <para>Specifies that Valgrind should send all of its messages
+ to the specified file. In fact, the file name used is
+ created by concatenating the text
+ <computeroutput>filename</computeroutput>, ".pid" and the
+ process ID, so as to create a file per process. The
+ specified file name may not be the empty string.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--log-socket=<ip-address:port-number></computeroutput></para>
+ <para>Specifies that Valgrind should send all of its messages
+ to the specified port at the specified IP address. The port
+ may be omitted, in which case port 1500 is used. If a
+ connection cannot be made to the specified socket, Valgrind
+ falls back to writing output to the standard error (stderr).
+ This option is intended to be used in conjunction with the
+ <computeroutput>valgrind-listener</computeroutput> program.
+ For further details, see <xref linkend="manual-core.comment"/>.</para>
+ </listitem>
+
+ </itemizedlist>
+ </sect2>
+
+
+<sect2 id="manual-core.erropts" xreflabel="Error-related Options">
+<title>Error-related options</title>
+
+<para>These options are used by all tools that can report
+errors, e.g. Memcheck, but not Cachegrind.</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><computeroutput>--demangle=no</computeroutput></para>
+ <para><computeroutput>--demangle=yes</computeroutput> [default]</para>
+ <para>Disable/enable automatic demangling (decoding) of C++
+ names. Enabled by default. When enabled, Valgrind will
+ attempt to translate encoded C++ procedure names back to
+ something approaching the original. The demangler handles
+ symbols mangled by g++ versions 2.X and 3.X.</para>
+
+ <para>An important fact about demangling is that function
+ names mentioned in suppressions files should be in their
+ mangled form. Valgrind does not demangle function names when
+ searching for applicable suppressions, because to do
+ otherwise would make suppressions file contents dependent on
+ the state of Valgrind's demangling machinery, and would also
+ be slow and pointless.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--num-callers=<number></computeroutput> [default=4]</para>
+ <para>By default, Valgrind shows four levels of function call
+ names to help you identify program locations. You can change
+ that number with this option. This can help in determining
+ the program's location in deeply-nested call chains. Note
+ that errors are commoned up using only the top three function
+ locations (the place in the current function, and that of its
+ two immediate callers). So this doesn't affect the total
+ number of errors reported.</para>
+
+ <para>The maximum value for this is 50. Note that higher
+ settings will make Valgrind run a bit more slowly and take a
+ bit more memory, but can be useful when working with programs
+ with deeply-nested call chains.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--error-limit=yes</computeroutput>
+ [default]</para>
+ <para><computeroutput>--error-limit=no</computeroutput></para>
+ <para>When enabled, Valgrind stops reporting errors after
+ 30000 in total, or 300 different ones, have been seen. This
+ is to stop the error tracking machinery from becoming a huge
+ performance overhead in programs with many errors.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--show-below-main=yes</computeroutput></para>
+ <para><computeroutput>--show-below-main=no</computeroutput>
+ [default]</para>
+ <para>By default, stack traces for errors do not show any
+ functions that appear beneath
+ <computeroutput>main()</computeroutput>; most of the time
+ it's uninteresting C library stuff. If this option is
+ enabled, these entries below
+ <computeroutput>main()</computeroutput> will be shown.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--suppressions=<filename></computeroutput>
+ [default: $PREFIX/lib/valgrind/default.supp]</para>
+ <para>Specifies an extra file from which to read descriptions
+ of errors to suppress. You may use as many extra
+ suppressions files as you like.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--gen-suppressions=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--gen-suppressions=yes</computeroutput></para>
+ <para>When enabled, Valgrind will pause after every error
+ shown, and print the line: <computeroutput>---- Print
+ suppression ? --- [Return/N/n/Y/y/C/c] ----</computeroutput></para>
+
+ <para>The prompt's behaviour is the same as for the
+ <computeroutput>--db-attach</computeroutput> option.</para>
+
+ <para>If you choose to, Valgrind will print out a suppression
+ for this error. You can then cut and paste it into a
+ suppression file if you don't want to hear about the error in
+ the future.</para>
+
+ <para>This option is particularly useful with C++ programs,
+ as it prints out the suppressions with mangled names, as
+ required.</para>
+
+ <para>Note that the suppressions printed are as specific as
+ possible. You may want to common up similar ones, eg. by
+ adding wildcards to function names. Also, sometimes two
+ different errors are suppressed by the same suppression, in
+ which case Valgrind will output the suppression more than
+ once, but you only need to have one copy in your suppression
+ file (but having more than one won't cause problems). Also,
+ the suppression name is given as <computeroutput><insert a
+ suppression name here></computeroutput>; the name doesn't
+ really matter, it's only used with the
+ <computeroutput>-v</computeroutput> option which prints out
+ all used suppression records.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--track-fds=no</computeroutput> [default]</para>
+ <para><computeroutput>--track-fds=yes</computeroutput></para>
+ <para>When enabled, Valgrind will print out a list of open
+ file descriptors on exit. Along with each file descriptor,
+ Valgrind prints out a stack backtrace of where the file was
+ opened and any details relating to the file descriptor such
+ as the file name or socket details.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--db-attach=no</computeroutput> [default]</para>
+ <para><computeroutput>--db-attach=yes</computeroutput></para>
+ <para>When enabled, Valgrind will pause after every error
+ shown, and print the line: <computeroutput>---- Attach to
+ debugger ? --- [Return/N/n/Y/y/C/c] ----</computeroutput></para>
+
+ <para>Pressing <literal>Ret</literal>, or
+ <literal>N Ret</literal> or <literal>n Ret</literal>, causes
+ Valgrind not to start a debugger for this error.</para>
+
+ <para><literal>Y Ret</literal> or <literal>y Ret</literal>
+ causes Valgrind to start a debugger, for the program at this
+ point. When you have finished with the debugger, quit from
+ it, and the program will continue. Trying to continue from
+ inside the debugger doesn't work.</para>
+
+ <para><literal>C Ret</literal> or <literal>c Ret</literal>
+ causes Valgrind not to start a debugger, and not to ask
+ again.</para>
+
+ <formalpara>
+ <title>Note:</title>
+ <para><computeroutput>--db-attach=yes</computeroutput>
+ conflicts with
+ <computeroutput>--trace-children=yes</computeroutput>. You
+ can't use them together. Valgrind refuses to start up in
+ this situation.</para>
+ </formalpara>
+ <para>1 May 2002: this is a historical relic which could be
+ easily fixed if it gets in your way. Mail me and complain if
+ this is a problem for you.</para> <para>Nov 2002: if you're
+ sending output to a logfile or to a network socket, I guess
+ this option doesn't make any sense. Caveat emptor.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--db-command=<command></computeroutput>
+ [default: gdb -nw %f %p]</para>
+ <para>This specifies how Valgrind will invoke the debugger.
+ By default it will use whatever GDB is detected at build
+ time, which is usually
+ <computeroutput>/usr/bin/gdb</computeroutput>. Using this
+ command, you can specify some alternative command to invoke
+ the debugger you want to use.</para>
+
+ <para>The command string given can include one or instances
+ of the <literal>%p</literal> and <literal>%f</literal>
+ expansions. Each instance of <literal>%p</literal> expands to
+ the PID of the process to be debugged and each instance of
+ <literal>%f</literal> expands to the path to the executable
+ for the process to be debugged.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--input-fd=<number></computeroutput>
+ [default=0, stdin]</para>
+ <para>When using
+ <computeroutput>--db-attach=yes</computeroutput> and
+ <computeroutput>--gen-suppressions=yes</computeroutput>,
+ Valgrind will stop so as to read keyboard input from you,
+ when each error occurs. By default it reads from the
+ standard input (stdin), which is problematic for programs
+ which close stdin. This option allows you to specify an
+ alternative file descriptor from which to read input.</para>
+ </listitem>
+
+ </itemizedlist>
+</sect2>
+
+<sect2 id="manual-core.mallocopts" xreflabel="malloc()-related Options">
+<title><computeroutput>malloc()</computeroutput>-related Options</title>
+
+<para>For tools that use their own version of
+<computeroutput>malloc()</computeroutput> (e.g. Memcheck and
+Addrcheck), the following options apply.</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><computeroutput>--alignment=<number></computeroutput>
+ [default: 8]</para>
+ <para>By default Valgrind's
+ <computeroutput>malloc</computeroutput>,
+ <computeroutput>realloc</computeroutput>, etc, return 4-byte
+ aligned addresses. These are suitable for any accesses on
+ x86 processors. Some programs might however assume that
+ <computeroutput>malloc</computeroutput> et al return 8- or
+ more aligned memory. The supplied value must be between 4
+ and 4096 inclusive, and must be a power of two.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--sloppy-malloc=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--sloppy-malloc=yes</computeroutput></para>
+ <para>When enabled, all requests for malloc/calloc are
+ rounded up to a whole number of machine words -- in other
+ words, made divisible by 4. For example, a request for 17
+ bytes of space would result in a 20-byte area being made
+ available. This works around bugs in sloppy libraries which
+ assume that they can safely rely on malloc/calloc requests
+ being rounded up in this fashion. Without the workaround,
+ these libraries tend to generate large numbers of errors when
+ they access the ends of these areas.</para>
+
+ <para>Valgrind snapshots dated 17 Feb 2002 and later are
+ cleverer about this problem, and you should no longer need to
+ use this flag. To put it bluntly, if you do need to use this
+ flag, your program violates the ANSI C semantics defined for
+ <computeroutput>malloc</computeroutput> and
+ <computeroutput>free</computeroutput>, even if it appears to
+ work correctly, and you should fix it, at least if you hope
+ for maximum portability.</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
+
+ <sect2 id="manual-core.rareopts" xreflabel="Rare Options">
+ <title>Rare Options</title>
+
+ <para>These options apply to all tools, as they affect certain
+ obscure workings of the Valgrind core. Most people won't need
+ to use these.</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><computeroutput>--run-libc-freeres=yes</computeroutput>
+ [default]</para>
+ <para><computeroutput>--run-libc-freeres=no</computeroutput></para>
+ <para>The GNU C library
+ (<computeroutput>libc.so</computeroutput>), which is used by
+ all programs, may allocate memory for its own uses. Usually
+ it doesn't bother to free that memory when the program ends -
+ there would be no point, since the Linux kernel reclaims all
+ process resources when a process exits anyway, so it would
+ just slow things down.</para>
+
+ <para>The glibc authors realised that this behaviour causes
+ leak checkers, such as Valgrind, to falsely report leaks in
+ glibc, when a leak check is done at exit. In order to avoid
+ this, they provided a routine called
+ <computeroutput>__libc_freeres</computeroutput> specifically
+ to make glibc release all memory it has allocated. Memcheck
+ and Addrcheck therefore try and run
+ <computeroutput>__libc_freeres</computeroutput> at
+ exit.</para>
+
+ <para>Unfortunately, in some versions of glibc,
+ <computeroutput>__libc_freeres</computeroutput> is
+ sufficiently buggy to cause segmentation faults. This is
+ particularly noticeable on Red Hat 7.1. So this flag is
+ provided in order to inhibit the run of
+ <computeroutput>__libc_freeres</computeroutput>. If your
+ program seems to run fine on Valgrind, but segfaults at exit,
+ you may find that
+ <computeroutput>--run-libc-freeres=no</computeroutput> fixes
+ that, although at the cost of possibly falsely reporting
+ space leaks in
+ <computeroutput>libc.so</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--weird-hacks=hack1,hack2,...</computeroutput></para>
+ <para>Pass miscellaneous hints to Valgrind which slightly
+ modify the simulated behaviour in nonstandard or dangerous
+ ways, possibly to help the simulation of strange features.
+ By default no hacks are enabled. Use with caution!
+ Currently known hacks are:</para>
+ <itemizedlist>
+ <listitem><para><computeroutput>lax-ioctls</computeroutput></para>
+ <para>Be very lax about ioctl handling; the only assumption
+ is that the size is correct. Doesn't require the full
+ buffer to be initialized when writing. Without this, using
+ some device drivers with a large number of strange ioctl
+ commands becomes very tiresome.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--signal-polltime=<time></computeroutput>
+ [default=50]</para>
+ <para>How often to poll for signals (in milliseconds). Only
+ applies for older kernels that need signal routing.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--lowlat-signals=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--lowlat-signals=yes</computeroutput></para>
+ <para>Improve wake-up latency when a thread receives a signal.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--lowlat-syscalls=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--lowlat-syscalls=yes</computeroutput></para>
+ <para>Improve wake-up latency when a thread's syscall
+ completes.</para>
+ </listitem>
+
+ </itemizedlist>
+</sect2>
+
+
+<sect2 id="manual-core.debugopts" xreflabel="Debugging Valgrind Options">
+<title>Debugging Valgrind Options</title>
+
+<para>There are also some options for debugging Valgrind itself.
+You shouldn't need to use them in the normal run of things.
+Nevertheless:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><computeroutput>--single-step=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--single-step=yes</computeroutput></para>
+ <para>When enabled, each x86 insn is translated separately
+ into instrumented code. When disabled, translation is done
+ on a per-basic-block basis, giving much better
+ translations.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--optimise=no</computeroutput></para>
+ <para><computeroutput>--optimise=yes</computeroutput> [default]</para>
+ <para>When enabled, various improvements are applied to the
+ intermediate code, mainly aimed at allowing the simulated
+ CPU's registers to be cached in the real CPU's registers over
+ several simulated instructions.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--profile=no</computeroutput></para>
+ <para><computeroutput>--profile=yes</computeroutput> [default]</para>
+ <para>When enabled, does crude internal profiling of Valgrind
+ itself. This is not for profiling your programs. Rather it
+ is to allow the developers to assess where Valgrind is
+ spending its time. The tools must be built for profiling for
+ this to work.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-syscalls=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--trace-syscalls=yes</computeroutput></para>
+ <para>Enable/disable tracing of system call intercepts.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-signals=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--trace-signals=yes</computeroutput></para>
+ <para>Enable/disable tracing of signal handling.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-sched=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--trace-sched=yes</computeroutput></para>
+ <para>Enable/disable tracing of thread scheduling events.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-pthread=none</computeroutput>
+ [default]</para>
+ <para><computeroutput>--trace-pthread=some</computeroutput></para>
+ <para><computeroutput>--trace-pthread=all</computeroutput></para>
+ <para>Specifies amount of trace detail for pthread-related
+ events.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-symtab=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--trace-symtab=yes</computeroutput></para>
+ <para>Enable/disable tracing of symbol table reading.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-malloc=no</computeroutput>
+ [default]</para>
+ <para><computeroutput>--trace-malloc=yes</computeroutput></para>
+ <para>Enable/disable tracing of malloc/free (et al)
+ intercepts.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--trace-codegen=XXXXX</computeroutput>
+ [default: 00000]</para>
+ <para>Enable/disable tracing of code generation. Code can be
+ printed at five different stages of translation; each
+ <computeroutput>X</computeroutput> element must be 0 or
+ 1.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--dump-error=<number></computeroutput>
+ [default: inactive]</para>
+ <para>After the program has exited, show gory details of the
+ translation of the basic block containing the <number>'th
+ error context. When used with
+ <computeroutput>--single-step=yes</computeroutput>, can show
+ the exact x86 instruction causing an error. This is all
+ fairly dodgy and doesn't work at all if threads are
+ involved.</para>
+ </listitem>
+
+ </itemizedlist>
+</sect2>
+
+
+<sect2 id="manual-core.defopts" xreflabel="Setting default options">
+<title>Setting default Options</title>
+
+<para>Note that Valgrind also reads options from three places:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The file <computeroutput>~/.valgrindrc</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para>The environment variable
+ <computeroutput>$VALGRIND_OPTS</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para>The file <computeroutput>./.valgrindrc</computeroutput></para>
+ </listitem>
+ </orderedlist>
+
+<para>These are processed in the given order, before the
+command-line options. Options processed later override those
+processed earlier; for example, options in
+<computeroutput>./.valgrindrc</computeroutput> will take
+precedence over those in
+<computeroutput>~/.valgrindrc</computeroutput>. The first two
+are particularly useful for setting the default tool to
+use.</para>
+
+<para>Any tool-specific options put in
+<computeroutput>$VALGRIND_OPTS</computeroutput> or the
+<computeroutput>.valgrindrc</computeroutput> files should be
+prefixed with the tool name and a colon. For example, if you
+want Memcheck to always do leak checking, you can put the
+following entry in <literal>~/.valgrindrc</literal>:</para>
+
+<programlisting><![CDATA[
+--memcheck:leak-check=yes]]></programlisting>
+
+<para>This will be ignored if any tool other than Memcheck is
+run. Without the <computeroutput>memcheck:</computeroutput>
+part, this will cause problems if you select other tools that
+don't understand
+<computeroutput>--leak-check=yes</computeroutput>.</para>
+
+</sect2>
+
+</sect1>
+
+
+<sect1 id="manual-core.clientreq"
+ xreflabel="The Client Request mechanism">
+<title>The Client Request mechanism</title>
+
+<para>Valgrind has a trapdoor mechanism via which the client
+program can pass all manner of requests and queries to Valgrind
+and the current tool. Internally, this is used extensively to
+make malloc, free, signals, threads, etc, work, although you
+don't see that.</para>
+
+<para>For your convenience, a subset of these so-called client
+requests is provided to allow you to tell Valgrind facts about
+the behaviour of your program, and conversely to make queries.
+In particular, your program can tell Valgrind about changes in
+memory range permissions that Valgrind would not otherwise know
+about, and so allows clients to get Valgrind to do arbitrary
+custom checks.</para>
+
+<para>Clients need to include a header file to make this work.
+Which header file depends on which client requests you use. Some
+client requests are handled by the core, and are defined in the
+header file <filename>valgrind.h</filename>. Tool-specific
+header files are named after the tool, e.g.
+<filename>memcheck.h</filename>. All header files can be found
+in the <literal>include</literal> directory of wherever Valgrind
+was installed.</para>
+
+<para>The macros in these header files have the magical property
+that they generate code in-line which Valgrind can spot.
+However, the code does nothing when not run on Valgrind, so you
+are not forced to run your program on Valgrind just because you
+use the macros in this file. Also, you are not required to link
+your program with any extra supporting libraries.</para>
+
+<para>Here is a brief description of the macros available in
+<filename>valgrind.h</filename>, which work with more than one
+tool (see the tool-specific documentation for explanations of the
+tool-specific macros).</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><computeroutput>RUNNING_ON_VALGRIND</computeroutput>:</term>
+ <listitem>
+ <para>returns 1 if running on Valgrind, 0 if running on the
+ real CPU.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>:</term>
+ <listitem>
+ <para>discard translations of code in the specified address
+ range. Useful if you are debugging a JITter or some other
+ dynamic code generation system. After this call, attempts to
+ execute code in the invalidated address range will cause
+ Valgrind to make new translations of that code, which is
+ probably the semantics you want. Note that this is
+ implemented naively, and involves checking all 200191 entries
+ in the translation table to see if any of them overlap the
+ specified address range. So try not to call it often, or
+ performance will nosedive. Note that you can be clever about
+ this: you only need to call it when an area which previously
+ contained code is overwritten with new code. You can choose
+ to write coode into fresh memory, and just call this
+ occasionally to discard large chunks of old code all at
+ once.</para>
+
+ <para><command>Warning:</command> minimally tested,
+ especially for tools other than Memcheck.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_COUNT_ERRORS</computeroutput>:</term>
+ <listitem>
+ <para>returns the number of errors found so far by Valgrind.
+ Can be useful in test harness code when combined with the
+ <computeroutput>--log-fd=-1</computeroutput> option; this
+ runs Valgrind silently, but the client program can detect
+ when errors occur. Only useful for tools that report errors,
+ e.g. it's useful for Memcheck, but for Cachegrind it will
+ always return zero because Cachegrind doesn't report
+ errors.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>:</term>
+ <listitem>
+ <para>If your program manages its own memory instead of using
+ the standard <computeroutput>malloc()</computeroutput> /
+ <computeroutput>new</computeroutput> /
+ <computeroutput>new[]</computeroutput>, tools that track
+ information about heap blocks will not do nearly as good a
+ job. For example, Memcheck won't detect nearly as many
+ errors, and the error messages won't be as informative. To
+ improve this situation, use this macro just after your custom
+ allocator allocates some new memory. See the comments in
+ <filename>valgrind.h</filename> for information on how to use
+ it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_FREELIKE_BLOCK</computeroutput>:</term>
+ <listitem>
+ <para>This should be used in conjunction with
+ <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>.
+ Again, see <filename>memcheck/memcheck.h</filename> for
+ information on how to use it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>:</term>
+ <listitem>
+ <para>This is similar to
+ <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>,
+ but is tailored towards code that uses memory pools. See the
+ comments in <filename>valgrind.h</filename> for information
+ on how to use it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_DESTROY_MEMPOOL</computeroutput>:</term>
+ <listitem>
+ <para>This should be used in conjunction with
+ <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>
+ Again, see the comments in <filename>valgrind.h</filename> for
+ information on how to use it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_MEMPOOL_ALLOC</computeroutput>:</term>
+ <listitem>
+ <para>This should be used in conjunction with
+ <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>
+ Again, see the comments in <filename>valgrind.h</filename> for
+ information on how to use it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_MEMPOOL_FREE</computeroutput>:</term>
+ <listitem>
+ <para>This should be used in conjunction with
+ <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>
+ Again, see the comments in <filename>valgrind.h</filename> for
+ information on how to use it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_NON_SIMD_CALL[0123]</computeroutput>:</term>
+ <listitem>
+ <para>executes a function of 0, 1, 2 or 3 args in the client
+ program on the <emphasis>real</emphasis> CPU, not the virtual
+ CPU that Valgrind normally runs code on. These are used in
+ various ways internally to Valgrind. They might be useful to
+ client programs.</para> <formalpara><title>Warning:</title>
+ <para>Only use these if you <emphasis>really</emphasis> know
+ what you are doing.</para>
+ </formalpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_PRINTF(format, ...)</computeroutput>:</term>
+ <listitem>
+ <para>printf a message to the log file when running under
+ Valgrind. Nothing is output if not running under Valgrind.
+ Returns the number of characters output.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>VALGRIND_PRINTF_BACKTRACE(format, ...)</computeroutput>:</term>
+ <listitem>
+ <para>printf a message to the log file along with a stack
+ backtrace when running under Valgrind. Nothing is output if
+ not running under Valgrind. Returns the number of characters
+ output.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+<para>Note that <filename>valgrind.h</filename> is included by
+all the tool-specific header files (such as
+<filename>memcheck.h</filename>), so you don't need to include it
+in your client if you include a tool-specific header.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.pthreads" xreflabel="Support for POSIX Pthreads">
+<title>Support for POSIX Pthreads</title>
+
+<para>Valgrind supports programs which use POSIX pthreads.
+Getting this to work was technically challenging but it all works
+well enough for significant threaded applications to work.</para>
+
+<para>It works as follows: threaded apps are (dynamically) linked
+against <literal>libpthread.so</literal>. Usually this is the
+one installed with your Linux distribution. Valgrind, however,
+supplies its own <literal>libpthread.so</literal> and
+automatically connects your program to it instead.</para>
+
+<para>The fake <literal>libpthread.so</literal> and Valgrind
+cooperate to implement a user-space pthreads package. This
+approach avoids the horrible implementation problems of
+implementing a truly multiprocessor version of Valgrind, but it
+does mean that threaded apps run only on one CPU, even if you
+have a multiprocessor machine.</para>
+
+<para>Valgrind schedules your threads in a round-robin fashion,
+with all threads having equal priority. It switches threads
+every 50000 basic blocks (typically around 300000 x86
+instructions), which means you'll get a much finer interleaving
+of thread executions than when run natively. This in itself may
+cause your program to behave differently if you have some kind of
+concurrency, critical race, locking, or similar, bugs.</para>
+
+<para>As of the Valgrind-1.0 release, the state of pthread
+support was as follows:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>Mutexes, condition variables, thread-specific data,
+ <computeroutput>pthread_once</computeroutput>, reader-writer
+ locks, semaphores, cleanup stacks, cancellation and thread
+ detaching currently work. Various attribute-like calls are
+ handled but ignored; you get a warning message.</para>
+ </listitem>
+
+ <listitem>
+ <para>Currently the following syscalls are thread-safe
+ (nonblocking): <literal>write</literal>,
+ <literal>read</literal>, <literal>nanosleep</literal>,
+ <literal>sleep</literal>, <literal>select</literal>,
+ <literal>poll</literal>, <literal>recvmsg</literal> and
+ <literal>accept</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Signals in pthreads are now handled properly(ish):
+ <literal>pthread_sigmask</literal>,
+ <literal>pthread_kill</literal>, <literal>sigwait</literal>
+ and <literal>raise</literal> are now implemented. Each thread
+ has its own signal mask, as POSIX requires. It's a bit
+ kludgey -- there's a system-wide pending signal set, rather
+ than one for each thread. But hey.</para>
+ </listitem>
+
+ </itemizedlist>
+
+<formalpara>
+<title>Note:</title>
+<para>As of 18 May 2002, the following threaded programs now work
+fine on my RedHat 7.2 box: Opera 6.0Beta2, KNode in KDE 3.0,
+Mozilla-0.9.2.1 and Galeon-0.11.3, both as supplied with RedHat
+7.2. Also Mozilla 1.0RC2. OpenOffice 1.0. MySQL 3.something
+(the current stable release).</para>
+</formalpara>
+
+</sect1>
+
+
+<sect1 id="manual-core.signals" xreflabel="Handling of Signals">
+<title>Handling of Signals</title>
+
+<para>Valgrind provides suitable handling of signals, so,
+provided you stick to POSIX stuff, you should be ok. Basic
+sigaction() and sigprocmask() are handled. Signal handlers may
+return in the normal way or do longjmp(); both should work ok.
+As specified by POSIX, a signal is blocked in its own handler.
+Default actions for signals should work as before. Etc,
+etc.</para>
+
+<para>Under the hood, dealing with signals is a real pain, and
+Valgrind's simulation leaves much to be desired. If your program
+does way-strange stuff with signals, bad things may happen. If
+so, let us know. We don't promise to fix it, but we'd at least
+like to be aware of it.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.install" xreflabel="Building and Installing">
+<title>Building and Installing</title>
+
+<para>We use the standard Unix
+<computeroutput>./configure</computeroutput>,
+<computeroutput>make</computeroutput>, <computeroutput>make
+install</computeroutput> mechanism, and we have attempted to
+ensure that it works on machines with kernel 2.4 or 2.6 and glibc
+2.2.X or 2.3.X. I don't think there is much else to say. There
+are no options apart from the usual
+<computeroutput>--prefix</computeroutput> that you should give to
+<computeroutput>./configure</computeroutput>.</para>
+
+<para>The <computeroutput>configure</computeroutput> script tests
+the version of the X server currently indicated by the current
+<computeroutput>$DISPLAY</computeroutput>. This is a known bug.
+The intention was to detect the version of the current XFree86
+client libraries, so that correct suppressions could be selected
+for them, but instead the test checks the server version. This
+is just plain wrong.</para>
+
+<para>If you are building a binary package of Valgrind for
+distribution, please read <literal>README_PACKAGERS</literal>
+<xref linkend="dist.readme-packagers"/>. It contains some
+important information.</para>
+
+<para>Apart from that, there's not much excitement here. Let us
+know if you have build problems.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.problems" xreflabel="If You Have Problems">
+<title>If You Have Problems</title>
+
+<para>Contact us at <ulink url="http://www.valgrind.org">http://www.valgrind.org</ulink>.</para>
+
+<para>See <xref linkend="manual-core.limits"/> for the known
+limitations of Valgrind, and for a list of programs which are
+known not to work on it.</para>
+
+<para>The translator/instrumentor has a lot of assertions in it.
+They are permanently enabled, and I have no plans to disable
+them. If one of these breaks, please mail us!</para>
+
+<para>If you get an assertion failure on the expression
+<computeroutput>chunkSane(ch)</computeroutput> in
+<computeroutput>vg_free()</computeroutput> in
+<filename>vg_malloc.c</filename>, this may have happened because
+your program wrote off the end of a malloc'd block, or before its
+beginning. Valgrind should have emitted a proper message to that
+effect before dying in this way. This is a known problem which
+we should fix.</para>
+
+<para>Read the
+<ulink url="http://www.valgrind.org/docs/faq/index.html">FAQ</ulink> for
+more advice about common problems, crashes, etc.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.limits" xreflabel="Limitations">
+<title>Limitations</title>
+
+<para>The following list of limitations seems depressingly long.
+However, most programs actually work fine.</para>
+
+<para>Valgrind will run x86-GNU/Linux ELF dynamically linked
+binaries, on a kernel 2.4.X or 2.6.X system, subject to
+the following constraints:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>No support for 3DNow instructions. If the translator
+ encounters these, Valgrind will generate a SIGILL when the
+ instruction is executed.</para>
+ </listitem>
+
+ <listitem>
+ <para>Pthreads support is improving, but there are still
+ significant limitations in that department. See the section
+ above on Pthreads. Note that your program must be dynamically
+ linked against <literal>libpthread.so</literal>, so that
+ Valgrind can substitute its own implementation at program
+ startup time. If you're statically linked against it, things
+ will fail badly.</para>
+ </listitem>
+
+ <listitem>
+ <para>Memcheck assumes that the floating point registers are
+ not used as intermediaries in memory-to-memory copies, so it
+ immediately checks definedness of values loaded from memory by
+ floating-point loads. If you want to write code which copies
+ around possibly-uninitialised values, you must ensure these
+ travel through the integer registers, not the FPU.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your program does its own memory management, rather
+ than using malloc/new/free/delete, it should still work, but
+ Valgrind's error checking won't be so effective. If you
+ describe your program's memory management scheme using "client
+ requests" (Section 3.7 of this manual), Memcheck can do
+ better. Nevertheless, using malloc/new and free/delete is
+ still the best approach.</para>
+ </listitem>
+
+ <listitem>
+ <para>Valgrind's signal simulation is not as robust as it
+ could be. Basic POSIX-compliant sigaction and sigprocmask
+ functionality is supplied, but it's conceivable that things
+ could go badly awry if you do weird things with signals.
+ Workaround: don't. Programs that do non-POSIX signal tricks
+ are in any case inherently unportable, so should be avoided if
+ possible.</para>
+ </listitem>
+
+ <listitem>
+ <para>Programs which switch stacks are not well handled.
+ Valgrind does have support for this, but I don't have great
+ faith in it. It's difficult -- there's no cast-iron way to
+ decide whether a large change in %esp is as a result of the
+ program switching stacks, or merely allocating a large object
+ temporarily on the current stack -- yet Valgrind needs to
+ handle the two situations differently.</para>
+ </listitem>
+
+ <listitem>
+ <para>x86 instructions, and system calls, have been
+ implemented on demand. So it's possible, although unlikely,
+ that a program will fall over with a message to that effect.
+ If this happens, please report ALL the details printed out, so
+ we can try and implement the missing feature.</para>
+ </listitem>
+
+ <listitem>
+ <para>x86 floating point works correctly, but floating-point
+ code may run even more slowly than integer code, due to my
+ simplistic approach to FPU emulation.</para>
+ </listitem>
+
+ <listitem>
+ <para>Memory consumption of your program is majorly increased
+ whilst running under Valgrind. This is due to the large
+ amount of administrative information maintained behind the
+ scenes. Another cause is that Valgrind dynamically translates
+ the original executable. Translated, instrumented code is
+ 14-16 times larger than the original (!) so you can easily end
+ up with 30+ MB of translations when running (eg) a web
+ browser.</para>
+ </listitem>
+
+ <listitem>
+ <para>Valgrind can handle dynamically-generated code just
+ fine. However, if you regenerate code over the top of old code
+ (ie. at the same memory addresses) Valgrind will not realise
+ the code has changed, and will run its old translations, which
+ will be out-of-date. You need to use the
+ VALGRIND_DISCARD_TRANSLATIONS client request in that case. For
+ the same reason gcc's <ulink
+ url="http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html">trampolines
+ for nested functions</ulink> are currently unsupported, see
+ <ulink url="http://bugs.kde.org/show_bug.cgi?id=69511">bug
+ 69511</ulink>.</para>
+ </listitem>
+
+ </itemizedlist>
+
+
+ <para>Programs which are known not to work are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>emacs starts up but immediately concludes it is out of
+ memory and aborts. Emacs has it's own memory-management
+ scheme, but I don't understand why this should interact so
+ badly with Valgrind. Emacs works fine if you build it to use
+ the standard malloc/free routines.</para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>Known platform-specific limitations, as of release 1.0.0:</para>
+ <itemizedlist>
+ <listitem>
+ <para>On Red Hat 7.3, there have been reports of link errors
+ (at program start time) for threaded programs using
+ <computeroutput>__pthread_clock_gettime</computeroutput> and
+ <computeroutput>__pthread_clock_settime</computeroutput>.
+ This appears to be due to
+ <computeroutput>/lib/librt-2.2.5.so</computeroutput> needing
+ them. Unfortunately I do not understand enough about this
+ problem to fix it properly, and I can't reproduce it on my
+ test RedHat 7.3 system. Please mail me if you have more
+ information / understanding.</para>
+ </listitem>
+ </itemizedlist>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.howworks" xreflabel="How It Works - A Rough Overview">
+<title>How It Works -- A Rough Overview</title>
+
+<para>Some gory details, for those with a passion for gory
+details. You don't need to read this section if all you want to
+do is use Valgrind. What follows is an outline of the machinery.
+A more detailed (and somewhat out of date) description is to be
+found <xref linkend="mc-tech-docs"/>.</para>
+
+<sect2 id="manual-core.startb" xreflabel="Getting Started">
+<title>Getting started</title>
+
+<para>Valgrind is compiled into a shared object, valgrind.so.
+The shell script valgrind sets the LD_PRELOAD environment
+variable to point to valgrind.so. This causes the .so to be
+loaded as an extra library to any subsequently executed
+dynamically-linked ELF binary, viz, the program you want to
+debug.</para>
+
+<para>The dynamic linker allows each .so in the process image to
+have an initialisation function which is run before main(). It
+also allows each .so to have a finalisation function run after
+main() exits.</para>
+
+<para>When valgrind.so's initialisation function is called by the
+dynamic linker, the synthetic CPU to starts up. The real CPU
+remains locked in valgrind.so for the entire rest of the program,
+but the synthetic CPU returns from the initialisation function.
+Startup of the program now continues as usual -- the dynamic
+linker calls all the other .so's initialisation routines, and
+eventually runs main(). This all runs on the synthetic CPU, not
+the real one, but the client program cannot tell the
+difference.</para>
+
+<para>Eventually main() exits, so the synthetic CPU calls
+valgrind.so's finalisation function. Valgrind detects this, and
+uses it as its cue to exit. It prints summaries of all errors
+detected, possibly checks for memory leaks, and then exits the
+finalisation routine, but now on the real CPU. The synthetic CPU
+has now lost control -- permanently -- so the program exits back
+to the OS on the real CPU, just as it would have done
+anyway.</para>
+
+<para>On entry, Valgrind switches stacks, so it runs on its own
+stack. On exit, it switches back. This means that the client
+program continues to run on its own stack, so we can switch back
+and forth between running it on the simulated and real CPUs
+without difficulty. This was an important design decision,
+because it makes it easy (well, significantly less difficult) to
+debug the synthetic CPU.</para>
+
+</sect2>
+
+
+<sect2 id="manual-core.engine"
+ xreflabel="The translation/instrumentation engine">
+<title>The translation/instrumentation engine</title>
+
+<para>Valgrind does not directly run any of the original
+program's code. Only instrumented translations are run.
+Valgrind maintains a translation table, which allows it to find
+the translation quickly for any branch target (code address). If
+no translation has yet been made, the translator - a just-in-time
+translator - is summoned. This makes an instrumented
+translation, which is added to the collection of translations.
+Subsequent jumps to that address will use this
+translation.</para>
+
+<para>Valgrind no longer directly supports detection of
+self-modifying code. Such checking is expensive, and in practice
+(fortunately) almost no applications need it. However, to help
+people who are debugging dynamic code generation systems, there
+is a Client Request (basically a macro you can put in your
+program) which directs Valgrind to discard translations in a
+given address range. So Valgrind can still work in this
+situation provided the client tells it when code has become
+out-of-date and needs to be retranslated.</para>
+
+<para>The JITter translates basic blocks -- blocks of
+straight-line-code -- as single entities. To minimise the
+considerable difficulties of dealing with the x86 instruction
+set, x86 instructions are first translated to a RISC-like
+intermediate code, similar to sparc code, but with an infinite
+number of virtual integer registers. Initially each insn is
+translated seperately, and there is no attempt at
+instrumentation.</para>
+
+<para>The intermediate code is improved, mostly so as to try and
+cache the simulated machine's registers in the real machine's
+registers over several simulated instructions. This is often
+very effective. Also, we try to remove redundant updates of the
+simulated machines's condition-code register.</para>
+
+<para>The intermediate code is then instrumented, giving more
+intermediate code. There are a few extra intermediate-code
+operations to support instrumentation; it is all refreshingly
+simple. After instrumentation there is a cleanup pass to remove
+redundant value checks.</para>
+
+<para>This gives instrumented intermediate code which mentions
+arbitrary numbers of virtual registers. A linear-scan register
+allocator is used to assign real registers and possibly generate
+spill code. All of this is still phrased in terms of the
+intermediate code. This machinery is inspired by the work of
+Reuben Thomas (Mite).</para>
+
+<para>Then, and only then, is the final x86 code emitted. The
+intermediate code is carefully designed so that x86 code can be
+generated from it without need for spare registers or other
+inconveniences.</para>
+
+<para>The translations are managed using a traditional LRU-based
+caching scheme. The translation cache has a default size of
+about 14MB.</para>
+
+</sect2>
+
+
+<sect2 id="manual-core.track"
+ xreflabel="Tracking the Status of Memory">
+<title>Tracking the Status of Memory</title>
+
+<para>Each byte in the process' address space has nine bits
+associated with it: one A bit and eight V bits. The A and V bits
+for each byte are stored using a sparse array, which flexibly and
+efficiently covers arbitrary parts of the 32-bit address space
+without imposing significant space or performance overheads for
+the parts of the address space never visited. The scheme used,
+and speedup hacks, are described in detail at the top of the
+source file <filename>coregrind/vg_memory.c</filename>, so you
+should read that for the gory details.</para>
+
+</sect2>
+
+
+
+<sect2 id="manual-core.syscalls" xreflabel="System calls">
+<title>System calls</title>
+
+<para>All system calls are intercepted. The memory status map is
+consulted before and updated after each call. It's all rather
+tiresome. See <filename>coregrind/vg_syscalls.c</filename> for
+details.</para>
+
+</sect2>
+
+
+<sect2 id="manual-core.syssignals" xreflabel="Signals">
+<title>Signals</title>
+
+<para>All system calls to sigaction() and sigprocmask() are
+intercepted. If the client program is trying to set a signal
+handler, Valgrind makes a note of the handler address and which
+signal it is for. Valgrind then arranges for the same signal to
+be delivered to its own handler.</para>
+
+<para>When such a signal arrives, Valgrind's own handler catches
+it, and notes the fact. At a convenient safe point in execution,
+Valgrind builds a signal delivery frame on the client's stack and
+runs its handler. If the handler longjmp()s, there is nothing
+more to be said. If the handler returns, Valgrind notices this,
+zaps the delivery frame, and carries on where it left off before
+delivering the signal.</para>
+
+<para>The purpose of this nonsense is that setting signal
+handlers essentially amounts to giving callback addresses to the
+Linux kernel. We can't allow this to happen, because if it did,
+signal handlers would run on the real CPU, not the simulated one.
+This means the checking machinery would not operate during the
+handler run, and, worse, memory permissions maps would not be
+updated, which could cause spurious error reports once the
+handler had returned.</para>
+
+<para>An even worse thing would happen if the signal handler
+longjmp'd rather than returned: Valgrind would completely lose
+control of the client program.</para>
+
+<para>Upshot: we can't allow the client to install signal
+handlers directly. Instead, Valgrind must catch, on behalf of
+the client, any signal the client asks to catch, and must
+delivery it to the client on the simulated CPU, not the real one.
+This involves considerable gruesome fakery; see
+<filename>coregrind/vg_signals.c</filename> for details.</para>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.example" xreflabel="An Example Run">
+<title>An Example Run</title>
+
+<para>This is the log for a run of a small program using Memcheck
+The program is in fact correct, and the reported error is as the
+result of a potentially serious code generation bug in GNU g++
+(snapshot 20010527).</para>
+
+<programlisting><![CDATA[
+sewardj@phoenix:~/newmat10$
+~/Valgrind-6/valgrind -v ./bogon
+==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1.
+==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward.
+==25832== Startup, with flags:
+==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp
+==25832== reading syms from /lib/ld-linux.so.2
+==25832== reading syms from /lib/libc.so.6
+==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0
+==25832== reading syms from /lib/libm.so.6
+==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3
+==25832== reading syms from /home/sewardj/Valgrind/valgrind.so
+==25832== reading syms from /proc/self/exe
+==25832== loaded 5950 symbols, 142333 line number locations
+==25832==
+==25832== Invalid read of size 4
+==25832== at 0x8048724: _ZN10BandMatrix6ReSizeEiii (bogon.cpp:45)
+==25832== by 0x80487AF: main (bogon.cpp:66)
+==25832== by 0x40371E5E: __libc_start_main (libc-start.c:129)
+==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon)
+==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd
+==25832==
+==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0)
+==25832== malloc/free: in use at exit: 0 bytes in 0 blocks.
+==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated.
+==25832== For a detailed leak analysis, rerun with: --leak-check=yes
+==25832==
+==25832== exiting, did 1881 basic blocks, 0 misses.
+==25832== 223 translations, 3626 bytes in, 56801 bytes out.]]></programlisting>
+
+<para>The GCC folks fixed this about a week before gcc-3.0
+shipped.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.warnings" xreflabel="Warning Messages">
+<title>Warning Messages You Might See</title>
+
+<para>Most of these only appear if you run in verbose mode
+(enabled by <computeroutput>-v</computeroutput>):</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><computeroutput>More than 50 errors detected.
+ Subsequent errors will still be recorded, but in less detail
+ than before.</computeroutput></para>
+ <para>After 50 different errors have been shown, Valgrind
+ becomes more conservative about collecting them. It then
+ requires only the program counters in the top two stack frames
+ to match when deciding whether or not two errors are really
+ the same one. Prior to this point, the PCs in the top four
+ frames are required to match. This hack has the effect of
+ slowing down the appearance of new errors after the first 50.
+ The 50 constant can be changed by recompiling Valgrind.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>More than 300 errors detected. I'm not
+ reporting any more. Final error counts may be inaccurate. Go
+ fix your program!</computeroutput></para>
+ <para>After 300 different errors have been detected, Valgrind
+ ignores any more. It seems unlikely that collecting even more
+ different ones would be of practical help to anybody, and it
+ avoids the danger that Valgrind spends more and more of its
+ time comparing new errors against an ever-growing collection.
+ As above, the 300 number is a compile-time constant.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>Warning: client switching
+ stacks?</computeroutput></para>
+ <para>Valgrind spotted such a large change in the stack
+ pointer, <literal>%esp</literal>, that it guesses the client
+ is switching to a different stack. At this point it makes a
+ kludgey guess where the base of the new stack is, and sets
+ memory permissions accordingly. You may get many bogus error
+ messages following this, if Valgrind guesses wrong. At the
+ moment "large change" is defined as a change of more that
+ 2000000 in the value of the <literal>%esp</literal> (stack
+ pointer) register.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>Warning: client attempted to close
+ Valgrind's logfile fd <number></computeroutput></para>
+ <para>Valgrind doesn't allow the client to close the logfile,
+ because you'd never see any diagnostic information after that
+ point. If you see this message, you may want to use the
+ <computeroutput>--log-fd=<number></computeroutput> option
+ to specify a different logfile file-descriptor number.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>Warning: noted but unhandled ioctl
+ <number></computeroutput></para>
+ <para>Valgrind observed a call to one of the vast family of
+ <computeroutput>ioctl</computeroutput> system calls, but did
+ not modify its memory status info (because I have not yet got
+ round to it). The call will still have gone through, but you
+ may get spurious errors after this as a result of the
+ non-update of the memory info.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>Warning: set address range perms: large
+ range <number></computeroutput></para>
+ <para>Diagnostic message, mostly for benefit of the valgrind
+ developers, to do with memory permissions.</para>
+ </listitem>
+
+ </itemizedlist>
+
+</sect1>
+</chapter>
diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml
new file mode 100644
index 0000000..844774b
--- /dev/null
+++ b/docs/xml/manual-intro.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="manual-intro" xreflabel="Introduction">
+<title>Introduction</title>
+
+<sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
+<title>An Overview of Valgrind</title>
+
+<para>Valgrind is a flexible system for debugging and profiling
+Linux-x86 executables. The system consists of a core, which
+provides a synthetic x86 CPU in software, and a series of tools,
+each of which performs some kind of debugging, profiling, or
+similar task. The architecture is modular, so that new tools can
+be created easily and without disturbing the existing
+structure.</para>
+
+<para>A number of useful tools are supplied as standard. In
+summary, these are:</para>
+
+<orderedlist>
+
+ <listitem>
+ <para><command>Memcheck</command> detects memory-management
+ problems in your programs. All reads and writes of memory
+ are checked, and calls to malloc/new/free/delete are
+ intercepted. As a result, Memcheck can detect the following
+ problems:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use of uninitialised memory</para>
+ </listitem>
+ <listitem>
+ <para>Reading/writing memory after it has been
+ free'd</para>
+ </listitem>
+ <listitem>
+ <para>Reading/writing off the end of malloc'd
+ blocks</para>
+ </listitem>
+ <listitem>
+ <para>Reading/writing inappropriate areas on the
+ stack</para>
+ </listitem>
+ <listitem>
+ <para>Memory leaks -- where pointers to malloc'd
+ blocks are lost forever</para>
+ </listitem>
+ <listitem>
+ <para>Mismatched use of malloc/new/new [] vs
+ free/delete/delete []</para>
+ </listitem>
+ <listitem>
+ <para>Overlapping <computeroutput>src</computeroutput> and
+ <computeroutput>dst</computeroutput> pointers in
+ <computeroutput>memcpy()</computeroutput> and related
+ functions</para></listitem> <listitem><para>Some misuses of
+ the POSIX pthreads API</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Problems like these can be difficult to find by other
+ means, often lying undetected for long periods, then causing
+ occasional, difficult-to-diagnose crashes.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>Addrcheck</command> is a lightweight version
+ of Memcheck. It is identical to Memcheck except for the
+ single detail that it does not do any uninitialised-value
+ checks. All of the other checks -- primarily the
+ fine-grained address checking -- are still done. The
+ downside of this is that you don't catch the
+ uninitialised-value errors that Memcheck can find.</para>
+
+ <para>But the upside is significant: programs run about twice
+ as fast as they do on Memcheck, and a lot less memory is
+ used. It still finds reads/writes of freed memory, memory
+ off the end of blocks and in other invalid places, bugs which
+ you really want to find before release!</para>
+
+ <para>Because Addrcheck is lighter and faster than Memcheck,
+ you can run more programs for longer, and so you may be able
+ to cover more test scenarios. Addrcheck was created because
+ one of us (Julian) wanted to be able to run a complete KDE
+ desktop session with checking. As of early November 2002, we
+ have been able to run KDE-3.0.3 on a 1.7 GHz P4 with 512 MB
+ of memory, using Addrcheck. Although the result is not
+ stellar, it's quite usable, and it seems plausible to run KDE
+ for long periods at a time like this, collecting up all the
+ addressing errors that appear.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>Cachegrind</command> is a cache profiler. It
+ performs detailed simulation of the I1, D1 and L2 caches in
+ your CPU and so can accurately pinpoint the sources of cache
+ misses in your code. If you desire, it will show the number
+ of cache misses, memory references and instructions accruing
+ to each line of source code, with per-function, per-module
+ and whole-program summaries. If you ask really nicely it
+ will even show counts for each individual x86
+ instruction.</para>
+
+ <para>Cachegrind auto-detects your machine's cache
+ configuration using the
+ <computeroutput>CPUID</computeroutput> instruction, and so
+ needs no further configuration info, in most cases.</para>
+
+ <para>Cachegrind is nicely complemented by Josef
+ Weidendorfer's amazing KCacheGrind visualisation tool
+ (<ulink url="http://kcachegrind.sourceforge.net">http://kcachegrind.sourceforge.net</ulink>),
+ a KDE application which presents these profiling results in a
+ graphical and easier-to-understand form.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>Helgrind</command> finds data races in
+ multithreaded programs. Helgrind looks for memory locations
+ which are accessed by more than one (POSIX p-)thread, but for
+ which no consistently used (pthread_mutex_)lock can be found.
+ Such locations are indicative of missing synchronisation
+ between threads, and could cause hard-to-find
+ timing-dependent problems.</para>
+
+ <para>Helgrind ("Hell's Gate", in Norse mythology) implements
+ the so-called "Eraser" data-race-detection algorithm, along
+ with various refinements (thread-segment lifetimes) which
+ reduce the number of false errors it reports. It is as yet
+ somewhat of an experimental tool, so your feedback is
+ especially welcomed here.</para>
+
+ <para>Helgrind has been hacked on extensively by Jeremy
+ Fitzhardinge, and we have him to thank for getting it to a
+ releasable state.</para>
+ </listitem>
+
+</orderedlist>
+
+
+<para>A number of minor tools (<command>Corecheck</command>,
+<command>Lackey</command> and <command>Nulgrind</command>) are
+also supplied. These aren't particularly useful -- they exist to
+illustrate how to create simple tools and to help the valgrind
+developers in various ways.</para>
+
+<para>Valgrind is closely tied to details of the CPU, operating
+system and to a less extent, compiler and basic C libraries. This
+makes it difficult to make it portable, so we have chosen at the
+outset to concentrate on what we believe to be a widely used
+platform: Linux on x86s. Valgrind uses the standard Unix
+<computeroutput>./configure</computeroutput>,
+<computeroutput>make</computeroutput>, <computeroutput>make
+install</computeroutput> mechanism, and we have attempted to
+ensure that it works on machines with kernel 2.2 or 2.4 and glibc
+2.1.X, 2.2.X or 2.3.1. This should cover the vast majority of
+modern Linux installations. Note that glibc-2.3.2+, with the
+NPTL (Native Posix Threads Library) package won't work. We hope
+to be able to fix this, but it won't be easy.</para>
+
+<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
+version 2. Some of the PThreads test cases,
+<computeroutput>pth_*.c</computeroutput>, are taken from
+"Pthreads Programming" by Bradford Nichols, Dick Buttlar &
+Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by
+O'Reilly & Associates, Inc.</para>
+
+</sect1>
+
+
+<sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
+<title>How to navigate this manual</title>
+
+<para>The Valgrind distribution consists of the Valgrind core,
+upon which are built Valgrind tools, which do different kinds of
+debugging and profiling. This manual is structured
+similarly.</para>
+
+<para>First, we describe the Valgrind core, how to use it, and
+the flags it supports. Then, each tool has its own chapter in
+this manual. You only need to read the documentation for the
+core and for the tool(s) you actually use, although you may find
+it helpful to be at least a little bit familar with what all
+tools do. If you're new to all this, you probably want to run
+the Memcheck tool. If you want to write a new tool, read
+<xref linkend="writing-tools"/>.</para>
+
+<para>Be aware that the core understands some command line flags,
+and the tools have their own flags which they know about. This
+means there is no central place describing all the flags that are
+accepted -- you have to read the flags documentation both for
+<xref linkend="manual-core"/> and for the tool you want to
+use.</para>
+
+</sect1>
+
+</chapter>
diff --git a/docs/xml/manual.xml b/docs/xml/manual.xml
new file mode 100644
index 0000000..f68f2eb
--- /dev/null
+++ b/docs/xml/manual.xml
@@ -0,0 +1,32 @@
+<?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">
+
+<book id="manual" xreflabel="Valgrind User Manual">
+
+ <bookinfo>
+ <title>Valgrind User Manual</title>
+ </bookinfo>
+
+ <xi:include href="manual-intro.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="manual-core.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../memcheck/docs/mc-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../addrcheck/docs/ac-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../cachegrind/docs/cg-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../massif/docs/ms-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../helgrind/docs/hg-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../none/docs/nl-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../corecheck/docs/cc-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../lackey/docs/lk-manual.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</book>
diff --git a/docs/xml/tech-docs.xml b/docs/xml/tech-docs.xml
new file mode 100644
index 0000000..3e8a60b
--- /dev/null
+++ b/docs/xml/tech-docs.xml
@@ -0,0 +1,18 @@
+<?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">
+
+<book id="tech-docs" xreflabel="Valgrind Technical Documentation">
+
+ <bookinfo>
+ <title>Valgrind Technical Documentation</title>
+ </bookinfo>
+
+ <xi:include href="../../memcheck/docs/mc-tech-docs.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="../../cachegrind/docs/cg-tech-docs.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="writing-tools.xml" parse="xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</book>
diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml
new file mode 100644
index 0000000..638d436
--- /dev/null
+++ b/docs/xml/vg-entities.xml
@@ -0,0 +1,12 @@
+<!-- misc. strings -->
+<!ENTITY vg-url "http://www.valgrind.org">
+<!ENTITY vg-jemail "jseward@valgrind.org">
+<!ENTITY vg-vemail "valgrind@valgrind.org">
+<!ENTITY vg-lifespan "2000-2004">
+<!ENTITY vg-users-list "http://lists.sourceforge.net/lists/listinfo/valgrind-users">
+
+<!-- valgrind release + version stuff -->
+<!ENTITY rel-type "Development release">
+<!ENTITY rel-version "2.1.2">
+<!ENTITY rel-date "July 18 2004">
+
diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml
new file mode 100644
index 0000000..b8b8aff
--- /dev/null
+++ b/docs/xml/writing-tools.xml
@@ -0,0 +1,1248 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
+<!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities;
+]>
+
+<chapter id="writing-tools" xreflabel="Writing a New Valgrind Tool">
+<title>Writing a New Valgrind Tool</title>
+
+<sect1 id="writing-tools.intro" xreflabel="Introduction">
+<title>Introduction</title>
+
+<sect2 id="writing-tools.supexec" xreflabel="Supervised Execution">
+<title>Supervised Execution</title>
+
+<para>Valgrind provides a generic infrastructure for supervising
+the execution of programs. This is done by providing a way to
+instrument programs in very precise ways, making it relatively
+easy to support activities such as dynamic error detection and
+profiling.</para>
+
+<para>Although writing a tool is not easy, and requires learning
+quite a few things about Valgrind, it is much easier than
+instrumenting a program from scratch yourself.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.tools" xreflabel="Tools">
+<title>Tools</title>
+
+<para>The key idea behind Valgrind's architecture is the division
+between its "core" and "tools".</para>
+
+<para>The core provides the common low-level infrastructure to
+support program instrumentation, including the x86-to-x86 JIT
+compiler, low-level memory manager, signal handling and a
+scheduler (for pthreads). It also provides certain services that
+are useful to some but not all tools, such as support for error
+recording and suppression.</para>
+
+<para>But the core leaves certain operations undefined, which
+must be filled by tools. Most notably, tools define how program
+code should be instrumented. They can also define certain
+variables to indicate to the core that they would like to use
+certain services, or be notified when certain interesting events
+occur. But the core takes care of all the hard work.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.execspaces" xreflabel="Execution Spaces">
+<title>Execution Spaces</title>
+
+<para>An important concept to understand before writing a tool is
+that there are three spaces in which program code executes:</para>
+
+
+<orderedlist>
+
+ <listitem>
+ <para>User space: this covers most of the program's execution.
+ The tool is given the code and can instrument it any way it
+ likes, providing (more or less) total control over the
+ code.</para>
+
+ <para>Code executed in user space includes all the program
+ code, almost all of the C library (including things like the
+ dynamic linker), and almost all parts of all other
+ libraries.</para>
+ </listitem>
+
+ <listitem>
+ <para>Core space: a small proportion of the program's execution
+ takes place entirely within Valgrind's core. This includes:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Dynamic memory management
+ (<computeroutput>malloc()</computeroutput> etc.)</para>
+ </listitem>
+ <listitem>
+ <para>Pthread operations and scheduling</para>
+ </listitem>
+ <listitem>
+ <para>Signal handling</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A tool has no control over these operations; it never
+ "sees" the code doing this work and thus cannot instrument it.
+ However, the core provides hooks so a tool can be notified
+ when certain interesting events happen, for example when when
+ dynamic memory is allocated or freed, the stack pointer is
+ changed, or a pthread mutex is locked, etc.</para>
+
+ <para>Note that these hooks only notify tools of events
+ relevant to user space. For example, when the core allocates
+ some memory for its own use, the tool is not notified of this,
+ because it's not directly part of the supervised program's
+ execution.</para>
+ </listitem>
+
+ <listitem>
+ <para>Kernel space: execution in the kernel. Two kinds:</para>
+ <orderedlist>
+ <listitem>
+ <para>System calls: can't be directly observed by either
+ the tool or the core. But the core does have some idea of
+ what happens to the arguments, and it provides hooks for a
+ tool to wrap system calls.</para>
+ </listitem>
+ <listitem>
+ <para>Other: all other kernel activity (e.g. process
+ scheduling) is totally opaque and irrelevant to the
+ program.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+
+ <listitem>
+ <para>It should be noted that a tool only has direct control
+ over code executed in user space. This is the vast majority
+ of code executed, but it is not absolutely all of it, so any
+ profiling information recorded by a tool won't be totally
+ accurate.</para>
+ </listitem>
+
+</orderedlist>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="writing-tools.writingatool" xreflabel="Writing a Tool">
+<title>Writing a Tool</title>
+
+
+<sect2 id="writing-tools.whywriteatool" xreflabel="Why write a tool?">
+<title>Why write a tool?</title>
+
+<para>Before you write a tool, you should have some idea of what
+it should do. What is it you want to know about your programs of
+interest? Consider some existing tools:</para>
+
+<itemizedlist>
+
+ <listitem>
+ <para><command>memcheck</command>: among other things, performs
+ fine-grained validity and addressibility checks of every memory
+ reference performed by the program.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>addrcheck</command>: performs lighterweight
+ addressibility checks of every memory reference performed by
+ the program.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>cachegrind</command>: tracks every instruction
+ and memory reference to simulate instruction and data caches,
+ tracking cache accesses and misses that occur on every line in
+ the program.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>helgrind</command>: tracks every memory access
+ and mutex lock/unlock to determine if a program contains any
+ data races.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>lackey</command>: does simple counting of
+ various things: the number of calls to a particular function
+ (<computeroutput>_dl_runtime_resolve()</computeroutput>); the
+ number of basic blocks, x86 instruction, UCode instructions
+ executed; the number of branches executed and the proportion of
+ those which were taken.</para>
+ </listitem>
+</itemizedlist>
+
+<para>These examples give a reasonable idea of what kinds of
+things Valgrind can be used for. The instrumentation can range
+from very lightweight (e.g. counting the number of times a
+particular function is called) to very intrusive (e.g.
+memcheck's memory checking).</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.suggestedtools" xreflabel="Suggested tools">
+<title>Suggested tools</title>
+
+<para>Here is a list of ideas we have had for tools that should
+not be too hard to implement.</para>
+
+<itemizedlist>
+ <listitem>
+ <para><command>branch profiler</command>: A machine's branch
+ prediction hardware could be simulated, and each branch
+ annotated with the number of predicted and mispredicted
+ branches. Would be implemented quite similarly to Cachegrind,
+ and could reuse the
+ <computeroutput>cg_annotate</computeroutput> script to annotate
+ source code.</para>
+
+ <para>The biggest difficulty with this is the simulation; the
+ chip-makers are very cagey about how their chips do branch
+ prediction. But implementing one or more of the basic
+ algorithms could still give good information.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>coverage tool</command>: Cachegrind can already
+ be used for doing test coverage, but it's massive overkill to
+ use it just for that.</para>
+
+ <para>It would be easy to write a coverage tool that records
+ how many times each basic block was recorded. Again, the
+ <computeroutput>cg_annotate</computeroutput> script could be
+ used for annotating source code with the gathered information.
+ Although, <computeroutput>cg_annotate</computeroutput> is only
+ designed for working with single program runs. It could be
+ extended relatively easily to deal with multiple runs of a
+ program, so that the coverage of a whole test suite could be
+ determined.</para>
+
+ <para>In addition to the standard coverage information, such a
+ tool could record extra information that would help a user
+ generate test cases to exercise unexercised paths. For
+ example, for each conditional branch, the tool could record all
+ inputs to the conditional test, and print these out when
+ annotating.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>run-time type checking</command>: A nice example
+ of a dynamic checker is given in this paper:</para>
+ <address>Debugging via Run-Time Type Checking
+ Alexey Loginov, Suan Hsi Yong, Susan Horwitz and Thomas Reps
+ Proceedings of Fundamental Approaches to Software Engineering
+ April 2001.
+ </address>
+
+ <para>Similar is the tool described in this paper:</para>
+ <address>Run-Time Type Checking for Binary Programs
+ Michael Burrows, Stephen N. Freund, Janet L. Wiener
+ Proceedings of the 12th International Conference on Compiler Construction (CC 2003)
+ April 2003.
+ </address>
+
+ <para>This approach can find quite a range of bugs,
+ particularly in C and C++ programs, and could be implemented
+ quite nicely as a Valgrind tool.</para>
+
+ <para>Ways to speed up this run-time type checking are
+ described in this paper:</para>
+ <address>Reducing the Overhead of Dynamic Analysis
+ Suan Hsi Yong and Susan Horwitz
+ Proceedings of Runtime Verification '02
+ July 2002.
+ </address>
+
+ <para>Valgrind's client requests could be used to pass
+ information to a tool about which elements need instrumentation
+ and which don't.</para>
+ </listitem>
+</itemizedlist>
+
+<para>We would love to hear from anyone who implements these or
+other tools.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.howtoolswork" xreflabel="How tools work">
+<title>How tools work</title>
+
+<para>Tools must define various functions for instrumenting
+programs that are called by Valgrind's core, yet they must be
+implemented in such a way that they can be written and compiled
+without touching Valgrind's core. This is important, because one
+of our aims is to allow people to write and distribute their own
+tools that can be plugged into Valgrind's core easily.</para>
+
+<para>This is achieved by packaging each tool into a separate
+shared object which is then loaded ahead of the core shared
+object <computeroutput>valgrind.so</computeroutput>, using the
+dynamic linker's <computeroutput>LD_PRELOAD</computeroutput>
+variable. Any functions defined in the tool that share the name
+with a function defined in core (such as the instrumentation
+function <computeroutput>SK_(instrument)()</computeroutput>)
+override the core's definition. Thus the core can call the
+necessary tool functions.</para>
+
+<para>This magic is all done for you; the shared object used is
+chosen with the <computeroutput>--tool</computeroutput> option to
+the <computeroutput>valgrind</computeroutput> startup script.
+The default tool used is
+<computeroutput>memcheck</computeroutput>, Valgrind's original
+memory checker.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.gettingcode" xreflabel="Getting the code">
+<title>Getting the code</title>
+
+<para>To write your own tool, you'll need to check out a copy of
+Valgrind from the CVS repository, rather than using a packaged
+distribution. This is because it contains several extra files
+needed for writing tools.</para>
+
+<para>To check out the code from the CVS repository, first login:</para>
+<programlisting><![CDATA[
+cvs -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind
+login]]></programlisting>
+
+<para>Then checkout the code. To get a copy of the current
+development version (recommended for the brave only):</para>
+<programlisting><![CDATA[
+cvs -z3 -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind
+co valgrind]]></programlisting>
+
+<para>To get a copy of the stable released branch:</para>
+<programlisting><![CDATA[
+cvs -z3 -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind
+co -r <TAG> valgrind]]></programlisting>
+
+<para>where <<computeroutput>TAG</computeroutput>> has the
+form <computeroutput>VALGRIND_X_Y_Z</computeroutput> for version
+X.Y.Z.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.gettingstarted" xreflabel="Getting started">
+<title>Getting started</title>
+
+<para>Valgrind uses GNU <computeroutput>automake</computeroutput>
+and <computeroutput>autoconf</computeroutput> for the creation of
+Makefiles and configuration. But don't worry, these instructions
+should be enough to get you started even if you know nothing
+about those tools.</para>
+
+<para>In what follows, all filenames are relative to Valgrind's
+top-level directory <computeroutput>valgrind/</computeroutput>.</para>
+
+<orderedlist>
+ <listitem>
+ <para>Choose a name for the tool, and an abbreviation that can
+ be used as a short prefix. We'll use
+ <computeroutput>foobar</computeroutput> and
+ <computeroutput>fb</computeroutput> as an example.</para>
+ </listitem>
+
+ <listitem>
+ <para>Make a new directory
+ <computeroutput>foobar/</computeroutput> which will hold the
+ tool.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy <computeroutput>none/Makefile.am</computeroutput>
+ into <computeroutput>foobar/</computeroutput>. Edit it by
+ replacing all occurrences of the string
+ <computeroutput>"none"</computeroutput> with
+ <computeroutput>"foobar"</computeroutput> and the one
+ occurrence of the string <computeroutput>"nl_"</computeroutput>
+ with <computeroutput>"fb_"</computeroutput>. It might be worth
+ trying to understand this file, at least a little; you might
+ have to do more complicated things with it later on. In
+ particular, the name of the
+ <computeroutput>vgskin_foobar_so_SOURCES</computeroutput>
+ variable determines the name of the tool's shared object, which
+ determines what name must be passed to the
+ <computeroutput>--tool</computeroutput> option to use the
+ tool.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy <filename>none/nl_main.c</filename> into
+ <computeroutput>foobar/</computeroutput>, renaming it as
+ <filename>fb_main.c</filename>. Edit it by changing the lines
+ in <computeroutput>SK_(pre_clo_init)()</computeroutput> to
+ something appropriate for the tool. These fields are used in
+ the startup message, except for
+ <computeroutput>bug_reports_to</computeroutput> which is used
+ if a tool assertion fails.</para>
+ </listitem>
+
+ <listitem>
+ <para>Edit <computeroutput>Makefile.am</computeroutput>,
+ adding the new directory
+ <computeroutput>foobar</computeroutput> to the
+ <computeroutput>SUBDIRS</computeroutput> variable.</para>
+ </listitem>
+
+ <listitem>
+ <para>Edit <computeroutput>configure.in</computeroutput>,
+ adding <computeroutput>foobar/Makefile</computeroutput> to the
+ <computeroutput>AC_OUTPUT</computeroutput> list.</para>
+ </listitem>
+
+ <listitem>
+ <para>Run:</para>
+<programlisting><![CDATA[
+ autogen.sh
+ ./configure --prefix=`pwd`/inst
+ make install]]></programlisting>
+
+ <para>It should automake, configure and compile without
+ errors, putting copies of the tool's shared object
+ <computeroutput>vgskin_foobar.so</computeroutput> in
+ <computeroutput>foobar/</computeroutput> and
+ <computeroutput>inst/lib/valgrind/</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>You can test it with a command like:</para>
+<programlisting><![CDATA[
+ inst/bin/valgrind --tool=foobar date]]></programlisting>
+
+ <para>(almost any program should work;
+ <computeroutput>date</computeroutput> is just an example).
+ The output should be something like this:</para>
+<programlisting><![CDATA[
+ ==738== foobar-0.0.1, a foobarring tool for x86-linux.
+ ==738== Copyright (C) 1066AD, and GNU GPL'd, by J. Random Hacker.
+ ==738== Built with valgrind-1.1.0, a program execution monitor.
+ ==738== Copyright (C) 2000-2003, and GNU GPL'd, by Julian Seward.
+ ==738== Estimated CPU clock rate is 1400 MHz
+ ==738== For more details, rerun with: -v
+ ==738== Wed Sep 25 10:31:54 BST 2002
+ ==738==]]></programlisting>
+
+ <para>The tool does nothing except run the program
+ uninstrumented.</para>
+ </listitem>
+
+</orderedlist>
+
+<para>These steps don't have to be followed exactly - you can
+choose different names for your source files, and use a different
+<computeroutput>--prefix</computeroutput> for
+<computeroutput>./configure</computeroutput>.</para>
+
+<para>Now that we've setup, built and tested the simplest
+possible tool, onto the interesting stuff...</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.writingcode" xreflabel="Writing the Code">
+<title>Writing the code</title>
+
+<para>A tool must define at least these four functions:</para>
+<programlisting><![CDATA[
+ SK_(pre_clo_init)()
+ SK_(post_clo_init)()
+ SK_(instrument)()
+ SK_(fini)()]]></programlisting>
+
+<para>Also, it must use the macro
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
+exactly once in its source code. If it doesn't, you will get a
+link error involving
+<computeroutput>VG_(skin_interface_major_version)</computeroutput>.
+This macro is used to ensure the core/tool interface used by the
+core and a plugged-in tool are binary compatible.</para>
+
+<para>In addition, if a tool wants to use some of the optional
+services provided by the core, it may have to define other
+functions.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.init" xreflabel="Initialisation">
+<title>Initialisation</title>
+
+<para>Most of the initialisation should be done in
+<computeroutput>SK_(pre_clo_init)()</computeroutput>. Only use
+<computeroutput>SK_(post_clo_init)()</computeroutput> if a tool
+provides command line options and must do some initialisation
+after option processing takes place
+(<computeroutput>"clo"</computeroutput> stands for "command line
+options").</para>
+
+<para>First of all, various "details" need to be set for a tool,
+using the functions
+<computeroutput>VG_(details_*)()</computeroutput>. Some are all
+compulsory, some aren't. Some are used when constructing the
+startup message,
+<computeroutput>detail_bug_reports_to</computeroutput> is used if
+<computeroutput>VG_(skin_panic)()</computeroutput> is ever
+called, or a tool assertion fails. Others have other uses.</para>
+
+<para>Second, various "needs" can be set for a tool, using the
+functions <computeroutput>VG_(needs_*)()</computeroutput>. They
+are mostly booleans, and can be left untouched (they default to
+<computeroutput>False</computeroutput>). They determine whether
+a tool can do various things such as: record, report and suppress
+errors; process command line options; wrap system calls; record
+extra information about malloc'd blocks, etc.</para>
+
+<para>For example, if a tool wants the core's help in recording
+and reporting errors, it must set the
+<computeroutput>skin_errors</computeroutput> need to
+<computeroutput>True</computeroutput>, and then provide
+definitions of six functions for comparing errors, printing out
+errors, reading suppressions from a suppressions file, etc.
+While writing these functions requires some work, it's much less
+than doing error handling from scratch because the core is doing
+most of the work. See the type
+<computeroutput>VgNeeds</computeroutput> in
+<filename>include/vg_skin.h</filename> for full details of all
+the needs.</para>
+
+<para>Third, the tool can indicate which events in core it wants
+to be notified about, using the functions
+<computeroutput>VG_(track_*)()</computeroutput>. These include
+things such as blocks of memory being malloc'd, the stack pointer
+changing, a mutex being locked, etc. If a tool wants to know
+about this, it should set the relevant pointer in the structure
+to point to a function, which will be called when that event
+happens.</para>
+
+<para>For example, if the tool want to be notified when a new
+block of memory is malloc'd, it should call
+<computeroutput>VG_(track_new_mem_heap)()</computeroutput> with
+an appropriate function pointer, and the assigned function will
+be called each time this happens.</para>
+
+<para>More information about "details", "needs" and "trackable
+events" can be found in
+<filename>include/vg_skin.h</filename>.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.instr" xreflabel="Instrumentation">
+<title>Instrumentation</title>
+
+<para><computeroutput>SK_(instrument)()</computeroutput> is the
+interesting one. It allows you to instrument
+<emphasis>UCode</emphasis>, which is Valgrind's RISC-like
+intermediate language. UCode is described in
+<xref linkend="mc-tech-docs.ucode"/>.</para>
+
+<para>The easiest way to instrument UCode is to insert calls to C
+functions when interesting things happen. See the tool "Lackey"
+(<filename>lackey/lk_main.c</filename>) for a simple example of
+this, or Cachegrind (<filename>cachegrind/cg_main.c</filename>)
+for a more complex example.</para>
+
+<para>A much more complicated way to instrument UCode, albeit one
+that might result in faster instrumented programs, is to extend
+UCode with new UCode instructions. This is recommended for
+advanced Valgrind hackers only! See Memcheck for an example.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.fini" xreflabel="Finalisation">
+<title>Finalisation</title>
+
+<para>This is where you can present the final results, such as a
+summary of the information collected. Any log files should be
+written out at this point.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.otherinfo" xreflabel="Other Important Information">
+<title>Other Important Information</title>
+
+<para>Please note that the core/tool split infrastructure is
+quite complex and not brilliantly documented. Here are some
+important points, but there are undoubtedly many others that I
+should note but haven't thought of.</para>
+
+<para>The file <filename>include/vg_skin.h</filename> contains
+all the types, macros, functions, etc. that a tool should
+(hopefully) need, and is the only <filename>.h</filename> file a
+tool should need to
+<computeroutput>#include</computeroutput>.</para>
+
+<para>In particular, you probably shouldn't use anything from the
+C library (there are deep reasons for this, trust us). Valgrind
+provides an implementation of a reasonable subset of the C
+library, details of which are in
+<filename>vg_skin.h</filename>.</para>
+
+<para>Similarly, when writing a tool, you shouldn't need to look
+at any of the code in Valgrind's core. Although it might be
+useful sometimes to help understand something.</para>
+
+<para><filename>vg_skin.h</filename> has a reasonable amount of
+documentation in it that should hopefully be enough to get you
+going. But ultimately, the tools distributed (Memcheck,
+Addrcheck, Cachegrind, Lackey, etc.) are probably the best
+documentation of all, for the moment.</para>
+
+<para>Note that the <computeroutput>VG_</computeroutput> and
+<computeroutput>SK_</computeroutput> macros are used heavily.
+These just prepend longer strings in front of names to avoid
+potential namespace clashes. We strongly recommend using the
+<computeroutput>SK_</computeroutput> macro for any global
+functions and variables in your tool, or writing a similar
+macro.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.advice" xreflabel="Words of Advice">
+<title>Words of Advice</title>
+
+<para>Writing and debugging tools is not trivial. Here are some
+suggestions for solving common problems.</para>
+
+
+<sect3 id="writing-tools.segfaults">
+<title>Segmentation Faults</title>
+
+<para>If you are getting segmentation faults in C functions used
+by your tool, the usual GDB command:</para>
+<screen><![CDATA[
+ gdb <prog> core]]></screen>
+<para>usually gives the location of the segmentation fault.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.debugfns">
+<title>Debugging C functions</title>
+
+<para>If you want to debug C functions used by your tool, you can
+attach GDB to Valgrind with some effort:</para>
+<orderedlist>
+ <listitem>
+ <para>Enable the following code in
+ <filename>coregrind/vg_main.c</filename> by changing
+ <computeroutput>if (0)</computeroutput>
+ into <computeroutput>if (1)</computeroutput>:
+<programlisting><![CDATA[
+ /* Hook to delay things long enough so we can get the pid and
+ attach GDB in another shell. */
+ if (0) {
+ Int p, q;
+ for ( p = 0; p < 50000; p++ )
+ for ( q = 0; q < 50000; q++ ) ;
+ }]]></programlisting>
+ and rebuild Valgrind.</para>
+ </listitem>
+
+ <listitem>
+ <para>Then run:</para>
+<programlisting><![CDATA[
+ valgrind <prog>]]></programlisting>
+ <para>Valgrind starts the program, printing its process id, and
+ then delays for a few seconds (you may have to change the loop
+ bounds to get a suitable delay).</para>
+ </listitem>
+
+ <listitem>
+ <para>In a second shell run:</para>
+<programlisting><![CDATA[
+ gdb <prog pid>]]></programlisting>
+ </listitem>
+
+</orderedlist>
+
+<para>GDB may be able to give you useful information. Note that
+by default most of the system is built with
+<computeroutput>-fomit-frame-pointer</computeroutput>, and you'll
+need to get rid of this to extract useful tracebacks from GDB.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.ucode-probs">
+<title>UCode Instrumentation Problems</title>
+
+<para>If you are having problems with your UCode instrumentation,
+it's likely that GDB won't be able to help at all. In this case,
+Valgrind's <computeroutput>--trace-codegen</computeroutput>
+option is invaluable for observing the results of
+instrumentation.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.misc">
+<title>Miscellaneous</title>
+
+<para>If you just want to know whether a program point has been
+reached, using the <computeroutput>OINK</computeroutput> macro
+(in <filename>include/vg_skin.h</filename>) can be easier than
+using GDB.</para>
+
+<para>The other debugging command line options can be useful too
+(run <computeroutput>valgrind -h</computeroutput> for the
+list).</para>
+
+</sect3>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="writing-tools.advtopics" xreflabel="Advanced Topics">
+<title>Advanced Topics</title>
+
+<para>Once a tool becomes more complicated, there are some extra
+things you may want/need to do.</para>
+
+<sect2 id="writing-tools.suppressions" xreflabel="Suppressions">
+<title>Suppressions</title>
+
+<para>If your tool reports errors and you want to suppress some
+common ones, you can add suppressions to the suppression files.
+The relevant files are
+<computeroutput>valgrind/*.supp</computeroutput>; the final
+suppression file is aggregated from these files by combining the
+relevant <computeroutput>.supp</computeroutput> files depending
+on the versions of linux, X and glibc on a system.</para>
+
+<para>Suppression types have the form
+<computeroutput>tool_name:suppression_name</computeroutput>. The
+<computeroutput>tool_name</computeroutput> here is the name you
+specify for the tool during initialisation with
+<computeroutput>VG_(details_name)()</computeroutput>.</para>
+
+</sect2>
+
+
+<!--
+<sect2 id="writing-tools.docs" xreflabel="Documentation">
+<title>Documentation</title>
+
+<para>As of version &rel-version;, Valgrind documentation has
+been converted to XML. Why?
+See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
+</para>
+
+
+<sect3 id="writing-tools.xml" xreflabel="The XML Toolchain">
+<title>The XML Toolchain</title>
+
+<para>If you are feeling conscientious and want to write some
+documentation for your tool, please use XML. The Valgrind
+Docs use the following toolchain and versions:</para>
+
+<programlisting>
+ xmllint: using libxml version 20607
+ xsltproc: using libxml 20607, libxslt 10102 and libexslt 802
+ pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b
+ pdftops: version 3.00
+ DocBook: version 4.2
+</programlisting>
+
+<para><command>Latency:</command> you should note that latency is
+a big problem: DocBook is constantly being updated, but the tools
+tend to lag behind somewhat. It is important that the versions
+get on with each other, so if you decide to upgrade something,
+then you need to ascertain whether things still work nicely -
+this *cannot* be assumed.</para>
+
+<para><command>Stylesheets:</command> The Valgrind docs use
+various custom stylesheet layers, all of which are in
+<computeroutput>valgrind/docs/lib/</computeroutput>. You
+shouldn't need to modify these in any way.</para>
+
+<para><command>Catalogs:</command> Assuming that you have the
+various tools listed above installed, you will probably need to
+modify
+<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
+so that the parser can find your DocBook installation. Catalogs
+provide a mapping from generic addresses to specific local
+directories on a given machine. Just add another
+<computeroutput>group</computeroutput> to this file, reflecting
+your local installation.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.writing" xreflabel="Writing the Documentation">
+<title>Writing the Documentation</title>
+
+<para>If you aren't confident using XML, or you have problems
+with the toolchain, then write your documentation in text format,
+email it to
+<computeroutput>valgrind@valgrind.org</computeroutput>, and
+someone will convert it to XML for you. Otherwise, follow these
+steps (using <computeroutput>foobar</computeroutput> as the
+example tool name again):</para>
+
+<orderedlist>
+
+ <listitem>
+ <para>Make a directory
+ <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy the xml tool documentation template file
+ <computeroutput>valgrind/docs/xml/tool-template.xml</computeroutput>
+ to <computeroutput>foobar/docs/</computeroutput>, and rename it
+ to
+ <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
+ <para><command>Note</command>: there is a *really stupid* tetex
+ bug with underscores in filenames, so don't use '_'.</para>
+ </listitem>
+
+ <listitem>
+ <para>Write the documentation. There are some helpful bits and
+ pieces on using xml markup in
+ <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
+ using the shell script
+ <filename>valgrind/docs/lib/xmlproc.sh</filename>.</para>
+<screen><![CDATA[
+% cd valgrind/docs/lib/
+% ./xmlproc.sh -valid ../../foobar/docs/fb-manual.xml
+]]></screen>
+
+ <para>If you have linked to other documents in the Valgrind
+ Documentation Set, you will get errors of the form:</para>
+
+<screen><![CDATA[
+fb-manual.xml:1632: element xref: validity error :
+ IDREF attribute linkend references an unknown ID "mc-tech-docs"
+]]></screen>
+
+ <para>Ignore (only) these - they will disappear when
+ <filename>fb-manual.xml</filename> is integrated into the
+ Set.</para>
+
+ <para>Because the xml toolchain is fragile, it is important to
+ ensure that <computeroutput>fb-manual.xml</computeroutput> won't
+ break the documentation set build. Note that just because an
+ xml file happily transforms to html does not necessarily mean
+ the same holds true for pdf/ps.</para>
+ </listitem>
+
+ <listitem>
+ <para>You can (re-)generate <filename>fb-manual.html</filename>
+ while you are writing <filename>fb-manual.xml</filename> to help
+ you see how it's looking. The generated file
+ <filename>fb-manual.html</filename> will be output in
+ <computeroutput>foobar/docs/</computeroutput>.</para>
+
+<screen><![CDATA[
+% ./xmlproc.sh -html ../../foobar/docs/fb-manual.xml
+]]></screen>
+ </listitem>
+
+ <listitem>
+ <para>When you have finished, generate html, pdf and ps output
+ to check all is well:</para>
+
+<screen><![CDATA[
+% cp ../../foobar/fb-manual.xml .
+% ./xmlproc.sh -test fb-manual.xml
+]]></screen>
+
+ <para>Check the output files (<filename>index.html,
+ fb-manual.pdf, fb-manual.ps</filename>) in
+ <computeroutput>/lib/test/</computeroutput> with the relevant
+ viewers. When you are happy and have finished tinkering with
+ <computeroutput>fb-manual.xml</computeroutput>:</para>
+
+<screen><![CDATA[
+% ./xmlproc.sh -clean fb-manual.xml
+]]></screen>
+</listitem>
+
+ <listitem>
+ <para>In order for your documentation to be included in the
+ User Manual, the relevant entries must be made in
+ <filename>/valgrind/docs/xml/vg-bookset.xml</filename> in this
+ format (hopefully, it should be pretty obvious):</para>
+
+<programlisting><![CDATA[
+<!ENTITY fb-manual SYSTEM "../../foobar/docs/fb-manual.xml">
+... ...
+&fb-manual;
+]]></programlisting>
+
+ <para>Send a patch for this to
+ <computeroutput>valgrind@valgrind.org</computeroutput>.</para>
+
+ <para>To achieve true anality, try for a full doc-set build:</para>
+<screen><![CDATA[
+% cd valgrind/docs/
+% make all
+]]></screen>
+ </listitem>
+
+</orderedlist>
+
+</sect3>
+
+</sect2>
+-->
+<sect2 id="writing-tools.docs" xreflabel="Documentation">
+<title>Documentation</title>
+
+<para>As of version &rel-version;, Valgrind documentation has
+been converted to XML. Why?
+See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
+</para>
+
+
+<sect3 id="writing-tools.xml" xreflabel="The XML Toolchain">
+<title>The XML Toolchain</title>
+
+<para>If you are feeling conscientious and want to write some
+documentation for your tool, please use XML. The Valgrind
+Docs use the following toolchain and versions:</para>
+
+<programlisting>
+ xmllint: using libxml version 20607
+ xsltproc: using libxml 20607, libxslt 10102 and libexslt 802
+ pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b
+ pdftops: version 3.00
+ DocBook: version 4.2
+</programlisting>
+
+<para><command>Latency:</command> you should note that latency is
+a big problem: DocBook is constantly being updated, but the tools
+tend to lag behind somewhat. It is important that the versions
+get on with each other, so if you decide to upgrade something,
+then you need to ascertain whether things still work nicely -
+this *cannot* be assumed.</para>
+
+<para><command>Stylesheets:</command> The Valgrind docs use
+various custom stylesheet layers, all of which are in
+<computeroutput>valgrind/docs/lib/</computeroutput>. You
+shouldn't need to modify these in any way.</para>
+
+<para><command>Catalogs:</command> Assuming that you have the
+various tools listed above installed, you will probably need to
+modify
+<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
+so that the parser can find your DocBook installation. Catalogs
+provide a mapping from generic addresses to specific local
+directories on a given machine. Just add another
+<computeroutput>group</computeroutput> to this file, reflecting
+your local installation.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.writing" xreflabel="Writing the Documentation">
+<title>Writing the Documentation</title>
+
+<para>Follow these steps (using <computeroutput>foobar</computeroutput>
+as the example tool name again):</para>
+
+<orderedlist>
+
+ <listitem>
+ <para>Make a directory
+ <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy the XML documentation file for the tool Nulgrind from
+ <computeroutput>valgrind/none/docs/nl-manual.xml</computeroutput>
+ to <computeroutput>foobar/docs/</computeroutput>, and rename it
+ to
+ <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
+ <para><command>Note</command>: there is a *really stupid* tetex
+ bug with underscores in filenames, so don't use '_'.</para>
+ </listitem>
+
+ <listitem>
+ <para>Write the documentation. There are some helpful bits and
+ pieces on using xml markup in
+ <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Include it in the User Manual by adding the relevant entry must
+ be added to <filename>valgrind/docs/xml/manual.xml</filename>. Copy
+ and edit an existing entry.</para>
+ </listitem>
+
+ <listitem>
+ <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
+ using the following command from within <filename>valgrind/docs/</filename>:
+ </para>
+<screen><![CDATA[
+% make valid
+]]></screen>
+
+ <para>You will probably get errors that look like this:</para>
+
+<screen><![CDATA[
+./xml/index.xml:5: element chapter: validity error : No declaration for
+attribute base of element chapter
+]]></screen>
+
+ <para>Ignore (only) these -- they're not important.</para>
+
+ <para>Because the xml toolchain is fragile, it is important to
+ ensure that <filename>fb-manual.xml</filename> won't
+ break the documentation set build. Note that just because an
+ xml file happily transforms to html does not necessarily mean
+ the same holds true for pdf/ps.</para>
+ </listitem>
+
+ <listitem>
+ <para>You can (re-)generate the HTML docs
+ while you are writing <filename>fb-manual.xml</filename> to help
+ you see how it's looking. The generated files end up in
+ <filename>valgrind/docs/html/</filename>. Use the following
+ command, within <filename>valgrind/docs/</filename>:</para>
+
+<screen><![CDATA[
+% make html-docs
+]]></screen>
+ </listitem>
+
+ <listitem>
+ <para>When you have finished, also generate pdf and ps output
+ to check all is well, from within <filename>valgrind/docs/</filename>:
+ </para>
+
+<screen><![CDATA[
+% make print-docs
+]]></screen>
+
+ <para>Check the output <filename>.pdf</filename> and
+ <filename>.ps</filename> files in
+ <computeroutput>valgrind/docs/print/</computeroutput>.
+ </para>
+</listitem>
+
+</orderedlist>
+
+</sect3>
+
+</sect2>
+
+
+<sect2 id="writing-tools.regtests" xreflabel="Regression Tests">
+<title>Regression Tests</title>
+
+<para>Valgrind has some support for regression tests. If you
+want to write regression tests for your tool:</para>
+
+<orderedlist>
+ <listitem>
+ <para>Make a directory
+ <computeroutput>foobar/tests/</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Edit <computeroutput>foobar/Makefile.am</computeroutput>,
+ adding <computeroutput>tests</computeroutput> to the
+ <computeroutput>SUBDIRS</computeroutput> variable.</para>
+ </listitem>
+
+ <listitem>
+ <para>Edit <computeroutput>configure.in</computeroutput>,
+ adding <computeroutput>foobar/tests/Makefile</computeroutput>
+ to the <computeroutput>AC_OUTPUT</computeroutput> list.</para>
+ </listitem>
+
+ <listitem>
+ <para>Write
+ <computeroutput>foobar/tests/Makefile.am</computeroutput>. Use
+ <computeroutput>memcheck/tests/Makefile.am</computeroutput> as
+ an example.</para>
+ </listitem>
+
+ <listitem>
+ <para>Write the tests, <computeroutput>.vgtest</computeroutput>
+ test description files,
+ <computeroutput>.stdout.exp</computeroutput> and
+ <computeroutput>.stderr.exp</computeroutput> expected output
+ files. (Note that Valgrind's output goes to stderr.) Some
+ details on writing and running tests are given in the comments
+ at the top of the testing script
+ <computeroutput>tests/vg_regtest</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Write a filter for stderr results
+ <computeroutput>foobar/tests/filter_stderr</computeroutput>.
+ It can call the existing filters in
+ <computeroutput>tests/</computeroutput>. See
+ <computeroutput>memcheck/tests/filter_stderr</computeroutput>
+ for an example; in particular note the
+ <computeroutput>$dir</computeroutput> trick that ensures the
+ filter works correctly from any directory.</para>
+ </listitem>
+
+</orderedlist>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.profiling" xreflabel="Profiling">
+<title>Profiling</title>
+
+<para>To do simple tick-based profiling of a tool, include the
+line:</para>
+<programlisting><![CDATA[
+ #include "vg_profile.c"]]></programlisting>
+<para>in the tool somewhere, and rebuild (you may have to
+<computeroutput>make clean</computeroutput> first). Then run
+Valgrind with the <computeroutput>--profile=yes</computeroutput>
+option.</para>
+
+<para>The profiler is stack-based; you can register a profiling
+event with
+<computeroutput>VGP_(register_profile_event)()</computeroutput>
+and then use the <computeroutput>VGP_PUSHCC</computeroutput> and
+<computeroutput>VGP_POPCC</computeroutput> macros to record time
+spent doing certain things. New profiling event numbers must not
+overlap with the core profiling event numbers. See
+<filename>include/vg_skin.h</filename> for details and Memcheck
+for an example.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.mkhackery" xreflabel="Other Makefile Hackery">
+<title>Other Makefile Hackery</title>
+
+<para>If you add any directories under
+<computeroutput>valgrind/foobar/</computeroutput>, you will need
+to add an appropriate <filename>Makefile.am</filename> to it, and
+add a corresponding entry to the
+<computeroutput>AC_OUTPUT</computeroutput> list in
+<filename>valgrind/configure.in</filename>.</para>
+
+<para>If you add any scripts to your tool (see Cachegrind for an
+example) you need to add them to the
+<computeroutput>bin_SCRIPTS</computeroutput> variable in
+<filename>valgrind/foobar/Makefile.am</filename>.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.ifacever" xreflabel="Core/tool Interface Versions">
+<title>Core/tool Interface Versions</title>
+
+<para>In order to allow for the core/tool interface to evolve
+over time, Valgrind uses a basic interface versioning system.
+All a tool has to do is use the
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
+macro exactly once in its code. If not, a link error will occur
+when the tool is built.</para>
+
+<para>The interface version number has the form X.Y. Changes in
+Y indicate binary compatible changes. Changes in X indicate
+binary incompatible changes. If the core and tool has the same
+major version number X they should work together. If X doesn't
+match, Valgrind will abort execution with an explanation of the
+problem.</para>
+
+<para>This approach was chosen so that if the interface changes
+in the future, old tools won't work and the reason will be
+clearly explained, instead of possibly crashing mysteriously. We
+have attempted to minimise the potential for binary incompatible
+changes by means such as minimising the use of naked structs in
+the interface.</para>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="writing-tools.finalwords" xreflabel="Final Words">
+<title>Final Words</title>
+
+<para>This whole core/tool business is under active development,
+although it's slowly maturing.</para>
+
+<para>The first consequence of this is that the core/tool
+interface will continue to change in the future; we have no
+intention of freezing it and then regretting the inevitable
+stupidities. Hopefully most of the future changes will be to add
+new features, hooks, functions, etc, rather than to change old
+ones, which should cause a minimum of trouble for existing tools,
+and we've put some effort into future-proofing the interface to
+avoid binary incompatibility. But we can't guarantee anything.
+The versioning system should catch any incompatibilities. Just
+something to be aware of.</para>
+
+<para>The second consequence of this is that we'd love to hear
+your feedback about it:</para>
+
+<itemizedlist>
+ <listitem>
+ <para>If you love it or hate it</para>
+ </listitem>
+ <listitem>
+ <para>If you find bugs</para>
+ </listitem>
+ <listitem>
+ <para>If you write a tool</para>
+ </listitem>
+ <listitem>
+ <para>If you have suggestions for new features, needs,
+ trackable events, functions</para>
+ </listitem>
+ <listitem>
+ <para>If you have suggestions for making tools easier to
+ write</para>
+ </listitem>
+ <listitem>
+ <para>If you have suggestions for improving this
+ documentation</para>
+ </listitem>
+ <listitem>
+ <para>If you don't understand something</para>
+ </listitem>
+</itemizedlist>
+
+<para>or anything else!</para>
+
+<para>Happy programming.</para>
+
+</sect1>
+
+</chapter>
diff --git a/docs/xml/xml_help.txt b/docs/xml/xml_help.txt
new file mode 100644
index 0000000..41d5ed7
--- /dev/null
+++ b/docs/xml/xml_help.txt
@@ -0,0 +1,174 @@
+ <!-- -*- sgml -*- -->
+----------------------------------------------
+Docbook Reference Manual (1999):
+- http://www.oreilly.com/catalog/docbook/
+DocBook XSL: The Complete Guide (2002)
+- http://www.sagehill.net/docbookxsl/index.html
+
+DocBook elements (what tags are allowed where)
+- http://www.oreilly.com/catalog/docbook/chapter/book/refelem.html
+
+Catalogs:
+- http://www.sagehill.net/docbookxsl/WriteCatalog.html
+
+
+----------------------------------------------
+xml to html markup transformations:
+
+<programlisting> --> <pre class="programlisting">
+<screen> --> <pre class="screen">
+<computeroutput> --> <tt class="computeroutput">
+<literal> --> <tt>
+<emphasis> --> <i>
+<command> --> <b class="command">
+<blockquote> --> <div class="blockquote">
+ <blockquote class="blockquote">
+
+Important: inside <screen> and <programlisting> blocks, do NOT
+use 'html entities' in your markup, eg. '<' If you *do* use
+them, they will be output verbatim, which is not what you want.
+
+
+----------------------------------------------
+
+<ulink url="http://..">http://kcachegrind.sourceforge.net</ulink>
+
+
+----------------------------------------------
+<variablelist> --> <dl>
+ <varlistentry>
+ <term>TTF</term> --> <dt>
+ <listitem>TrueType fonts.</listitem> --> <dd>
+ </varlistentry>
+</variablelist> --> <dl>
+
+
+----------------------------------------------
+<itemizedlist> --> <ul>
+ <listitem> --> <li>
+ <para>....</para>
+ <para>....</para>
+ </listitem> --> </li>
+</itemizedlist> --> </ul>
+
+
+----------------------------------------------
+<orderedlist> --> <ol>
+ <listitem> --> <li>
+ <para>....</para>
+ <para>....</para>
+ </listitem> --> </li>
+</orderedlist> --> </ol>
+
+
+----------------------------------------------
+To achieve this:
+
+This is a paragraph of text before a list:
+
+ * some text
+
+ * some more text
+
+and this is some more text after the list.
+
+Do this:
+<para>This is a paragraph of text before a list:</para>
+<itemizedlist>
+ <listitem>
+ <para>some text</para>
+ </listitem>
+ <listitem>
+ <para>some more text</para>
+ </listitem>
+</itemizedlist>
+
+
+----------------------------------------------
+To achieve this:
+For further details, see <a href="clientreq">The Mechanism</a>
+
+Do this:
+
+ Given:
+ <sect1 id="clientreq" xreflabel="The Mechanism">
+ <title>The Mechanism</title>
+ <para>...</para>
+ </sect1>
+
+ Then do:
+ For further details, see <xref linkend="clientreq"/>.
+
+
+----------------------------------------------
+To achieve this:
+<p><b>Warning:</b> Only do this if ...</p>
+
+Do this:
+<formalpara>
+ <title>Warning:</title>
+ <para>Only do this if ...</para>
+</formalpara>
+
+Or this:
+<para><command>Warning:</command> Only do this if ... </para>
+
+
+----------------------------------------------
+To achieve this:
+<p>It uses the Eraser algorithm described in:<br />
+<br />
+ Eraser: A Dynamic Data Race Detector for Multithreaded Programs<br />
+ Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson<br />
+ ACM Transactions on Computer Systems, 15(4):391-411<br />
+ November 1997.<br />
+</p>
+
+Do this:
+<literallayout>
+It uses the Eraser algorithm described in:
+
+ Eraser: A Dynamic Data Race Detector for Multithreaded Programs
+ Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson
+ ACM Transactions on Computer Systems, 15(4):391-411
+ November 1997.
+</literallayout>
+
+
+----------------------------------------------
+To achieve this:
+<pre>
+/* Hook to delay things long enough so we can get the pid
+ and attach GDB in another shell. */
+if (0) {
+ Int p, q;
+ for ( p = 0; p < 50000; p++ )
+ for ( q = 0; q < 50000; q++ ) ;
+</pre>
+
+Do this:
+<programlisting><![CDATA[
+/* Hook to delay things long enough so we can get the pid
+ and attach GDB in another shell. */
+if (0) {
+ Int p, q;
+ for ( p = 0; p < 50000; p++ )
+ for ( q = 0; q < 50000; q++ ) ;
+}]]></programlisting>
+
+
+(do the same thing for <screen> tag)
+
+
+----------------------------------------------
+To achieve this:
+ where <i><code>TAG</code></i> has the ...
+
+Do this:
+ where <emphasis><computeroutput>TAG</computeroutput></emphasis> has the ...
+
+Note: you cannot put <emphasis> inside <computeroutput>, unfortunately.
+
+----------------------------------------------
+
+Any other helpful hints? Please tell us.