Update docs for 1.0.4, including adding the FAQ.

MERGE TO HEAD

git-svn-id: svn://svn.valgrind.org/valgrind/branches/VALGRIND_1_0_BRANCH@1225

diff --git a/FAQ.txt b/FAQ.txt
new file mode 100644 (file)
index 0000000..31de59f
--- /dev/null
+++ b/FAQ.txt
@@ -0,0 +1,82 @@
+
+
+Q1. Programs run OK on valgrind, but at exit produce a bunch
+    of errors a bit like this
+
+    ==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)
+
+    and then die with a segmentation fault.
+
+A1. When the program exits, valgrind runs the procedure
+    __libc_freeres() 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.
+
+    Problem is that running __libc_freeres() in older glibc versions
+    causes this crash.  
+
+    WORKAROUND FOR 1.0.X versions of valgrind: The simple fix is to
+    find in valgrind's sources, the one and only call to
+    __libc_freeres() and comment it out, then rebuild the system.  In
+    the 1.0.3 version, this call is on line 584 of vg_clientfuncs.c.
+    This may mean you get false reports of space leaks in glibc, but
+    it at least avoids the crash.
+
+    WORKAROUND FOR 1.1.X and later versions of valgrind: use the
+    --run-libc-freeres=no flag.
+
+
+Q2. My program dies complaining that syscall 197 is unimplemented.
+
+A2. 197, which is fstat64, is supported by valgrind.  The problem is
+    that the /usr/include/asm/unistd.h on the machine on which your
+    valgrind was built, doesn't match your kernel -- or, to be more 
+    specific, glibc is asking your kernel to do a syscall which is
+    not listed in /usr/include/asm/unistd.h.
+
+    The fix is simple.  Somewhere near the top of vg_syscall_mem.c,
+    add the following line:
+
+       #define __NR_fstat64            197
+
+    Rebuild and try again.  The above line should appear before any
+    uses of the __NR_fstat64 symbol in that file.  If you look at the
+    place where __NR_fstat64 is used in vg_syscall_mem.c, it will be
+    obvious why this fix works.  NOTE for valgrind versions 1.1.0
+    and later, the relevant file is actually coregrind/vg_syscalls.c.
+
+
+This buffer is for notes you don't want to save, and for Lisp evaluation.
+If you want to create a file, visit that file with C-x C-f,
+then enter the text in that file's own buffer.
+
+20021008: confirmed as working on RHAS 2.1.
+< 
+<        /* HACK for R H Advanced server.  Ignore all the above and
+<           start the search 18 pages below the "obvious" start point.
+<           God knows why.  Seems like we can't go into the highest 18
+<           pages of the stack.  This is not good! -- the 18 pages is
+<           determined just by looking for the highest proddable
+<           address.  It would be nice to see some kernel or libc or
+<           something code to justify this.  */
+< 
+<        /* 0xBFFEE000 is 0xC0000000 - 18 pages */
+<        sp = 0xBFFEE000; 
+< 
+<        /* end of HACK for R H Advanced server. */
+< 
+---
+>  
+649d635
+< 

diff --git a/Makefile.am b/Makefile.am
index ffc440b062b48de7ca8d29a57411c18f3ad342cc..7211b8bfbacb958e9841b167eb269b1ea8e237d2 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -23,7 +23,7 @@ bzdist: dist
        gunzip -c $(PACKAGE)-$(VERSION).tar.gz | bzip2 > $(PACKAGE)-$(VERSION).tar.bz2
 
 EXTRA_DIST = $(val_DATA) \
-       PATCHES_APPLIED ACKNOWLEDGEMENTS \
+       PATCHES_APPLIED ACKNOWLEDGEMENTS FAQ.txt \
        README_KDE3_FOLKS README_PACKAGERS CURRENT_BUG_STATUS \
        README_MISSING_SYSCALL_OR_IOCTL TODO dosyms vg_libpthread.vs \
        valgrind.spec valgrind.spec.in

diff --git a/docs/manual.html b/docs/manual.html
index 013059ec7f0b7202963c4f4161aec70f68b08d46..e4bd5b5d2d8839289922e2faea1f88312f26806d 100644 (file)
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -25,8 +25,8 @@
 <body bgcolor="#ffffff">
 
 <a name="title">&nbsp;</a>
-<h1 align=center>Valgrind, version 1.0.0</h1>
-<center>This manual was last updated on 20020726</center>
+<h1 align=center>Valgrind, version 1.0.4</h1>
+<center>This manual was last updated on 20021013</center>
 <p>
 
 <center>
@@ -42,6 +42,14 @@ Linux-x86 executables.
 <p>
 
 <hr width="100%">
+
+<p>As of version 1.0.4, there is a <code>FAQ.txt</code> in the source
+distribution.  This might help in some common problem situations.
+
+<p>
+
+<hr width="100%">
+
 <a name="contents"></a>
 <h2>Contents of this manual</h2>
 
@@ -1369,6 +1377,9 @@ of these breaks, please mail me!
 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 I should fix.
+
+<p>As of version 1.0.4, there is a <code>FAQ.txt</code> in the source
+distribution.  This might help in some common problem situations.
 <p>
 
 <hr width="100%">

diff --git a/vg_mylibc.c b/vg_mylibc.c
index 4a5f1f7a97b877f46edb738691e809826421810e..7f154bdbbe429530931246ec549c10d71e634447 100644 (file)
--- a/vg_mylibc.c
+++ b/vg_mylibc.c
@@ -960,6 +960,8 @@ void VG_(assert_fail) ( Char* expr, Char* file, Int line, Char* fn )
    VG_(printf)("\n%s: %s:%d (%s): Assertion `%s' failed.\n",
                "valgrind", file, line, fn, expr );
    VG_(pp_sched_status)();
+   VG_(printf)("\nFor fixes for some common problems, "
+               "see FAQ.txt in the source distribution.\n\n");
    VG_(printf)("Please report this bug to me at: %s\n\n", VG_EMAIL_ADDR);
    VG_(shutdown_logging)();
    VG_(exit)(1);
@@ -970,6 +972,8 @@ void VG_(panic) ( Char* str )
    VG_(printf)("\nvalgrind: the `impossible' happened:\n   %s\n", str);
    VG_(printf)("Basic block ctr is approximately %llu\n", VG_(bbs_done) );
    VG_(pp_sched_status)();
+   VG_(printf)("\nFor fixes for some common problems, "
+               "see FAQ.txt in the source distribution.\n\n");
    VG_(printf)("Please report this bug to me at: %s\n\n", VG_EMAIL_ADDR);
    VG_(shutdown_logging)();
    VG_(exit)(1);