From: Julian Seward Date: Wed, 1 May 2002 12:38:06 +0000 (+0000) Subject: Bring manual up-to-date and add stuff about pthread support. X-Git-Tag: svn/VALGRIND_1_0_3~263 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6b485c7718f61329bad4398f166989e199ba879b;p=thirdparty%2Fvalgrind.git Bring manual up-to-date and add stuff about pthread support. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@189 --- diff --git a/cachegrind/docs/manual.html b/cachegrind/docs/manual.html index daaa1535d1..db1d28326f 100644 --- a/cachegrind/docs/manual.html +++ b/cachegrind/docs/manual.html @@ -24,8 +24,8 @@   -

Valgrind, snapshot 20020324

-
This manual was minimally updated on 20020415
+

Valgrind, snapshot 20020501

+
This manual was majorly updated on 20020501

@@ -57,8 +57,10 @@ Linux-x86 executables. 2.5  Command-line flags
2.6  Explaination of error messages
2.7  Writing suppressions files
- 2.8  Building and installing
- 2.9  If you have problems
+ 2.8  The Client Request mechanism
+ 2.9  Support for POSIX pthreads
+ 2.10  Building and installing
+ 2.11  If you have problems

3  Details of the checking machinery

3.1  Valid-value (V) bits
@@ -112,18 +114,12 @@ 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 I have chosen at the outset to concentrate on what I believe to be a widely used platform: Red Hat -Linux 7.2, on x86s. I believe that it will work without significant -difficulty on other x86 GNU/Linux systems which use the 2.4 kernel and -GNU libc 2.2.X, for example SuSE 7.1 and Mandrake 8.0. Red Hat 6.2 is -also supported. It has worked in the past, and probably still does, -on RedHat 7.1 and 6.2. Note that I haven't compiled it on RedHat 7.1 -and 6.2 for a while, so they may no longer work now. -

-(Early Feb 02: after feedback from the KDE people it also works better -on other Linuxes). -

-At some point in the past, Valgrind has also worked on Red Hat 6.2 -(x86), thanks to the efforts of Rob Noble. +Linux 7.2, on x86s. Valgrind uses the standard Unix +./configure, make, make install +mechanism, and I have attempted to ensure that it works on machines +with kernel 2.2 or 2.4 and glibc 2.1.X or 2.2.X. This should cover +the vast majority of modern Linux installations. +

Valgrind is licensed under the GNU General Public License, version @@ -148,26 +144,27 @@ checks every memory access. All detected errors are written to a log. When the program finishes, Valgrind searches for and reports on leaked memory. -

You can run pretty much any dynamically linked ELF x86 executable using -Valgrind. Programs run 25 to 50 times slower, and take a lot more -memory, than they usually would. It works well enough to run large -programs. For example, the Konqueror web browser from the KDE Desktop -Environment, version 2.1.1, runs slowly but usably on Valgrind. +

You can run pretty much any dynamically linked ELF x86 executable +using Valgrind. Programs run 25 to 50 times slower, and take a lot +more memory, than they usually would. It works well enough to run +large programs. For example, the Konqueror web browser from the KDE +Desktop Environment, version 3.0, runs slowly but usably on Valgrind.

Valgrind simulates every single instruction your program executes. Because of this, it finds errors not only in your application but also -in all supporting dynamically-linked (.so-format) libraries, including -the GNU C library, the X client libraries, Qt, if you work with KDE, and -so on. That often includes libraries, for example the GNU C library, -which contain memory access violations, but which you cannot or do not -want to fix. +in all supporting dynamically-linked (.so-format) +libraries, including the GNU C library, the X client libraries, Qt, if +you work with KDE, and so on. That often includes libraries, for +example the GNU C library, which contain memory access violations, but +which you cannot or do not want to fix.

Rather than swamping you with errors in which you are not interested, Valgrind allows you to selectively suppress errors, by recording them in a suppressions file which is read when Valgrind -starts up. As supplied, Valgrind comes with a suppressions file -designed to give reasonable behaviour on Red Hat 7.2 (also 7.1 and -6.2) when running text-only and simple X applications. +starts up. The build mechanism attempts to select suppressions which +give reasonable behaviour for the libc and XFree86 versions detected +on your machine. +

Section 6 shows an example of use.

@@ -185,9 +182,25 @@ debugging info enabled (the -g flag). 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. +debugger. -

Then just run your application, but place the word +

+A plausible compromise is to use -g -O. +Optimisation levels above -O have been observed, on very +rare occasions, to cause gcc to generate code which fools Valgrind's +error tracking machinery into wrongly reporting uninitialised value +errors. -O gets you the vast majority of the benefits of +higher optimisation levels anyway, so you don't lose much there. + +

+Note that as of 1 May 2002 Valgrind does not understand the DWARF +debugging format, which is unfortunate since the upcoming gcc-3.1 uses +it by default. Valgrind only knows about the older "stabs" format. +If you use gcc-3.1 or above, you can still ask for stabs-format debug +info by passing -gstabs to gcc. + +

+Then just run your application, but place the word valgrind in front of your usual command-line invokation. Note that you should run the real (machine-code) executable here. If your application is started by, for example, a shell or perl script, @@ -195,7 +208,7 @@ 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 /bin/sh, /usr/bin/perl, or whatever interpreter you're using. -This almost certainly isn't what you want and can be hugely confusing. +This almost certainly isn't what you want and can be confusing.

2.2  The commentary

@@ -265,6 +278,17 @@ later uses them, will generate several error messages. The first such error message may well give the most direct clue to the root cause of the problem. +

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 vg_include.h and can be increased +if necessary. +

2.4  Suppressing errors

@@ -272,14 +296,15 @@ Valgrind detects 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. By default -this file is redhat72.supp, located in the Valgrind -installation directory. +Valgrind reads a list of errors to suppress at startup. +A default suppression file is cooked up by the +./configure script. -

You can modify and add to the suppressions file at your leisure, or -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. +

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.

Each error to be suppressed is described very specifically, to minimise the possibility that a suppression-directive inadvertantly @@ -305,6 +330,10 @@ You invoke Valgrind like this: valgrind [options-for-Valgrind] your-prog [options for your-prog] +

Note that Valgrind also reads options from the environment variable +$VALGRIND, and processes them before the command-line +options. +

Valgrind's default settings succeed in giving reasonable behaviour in most cases. Available options, in no particular order, are as follows: @@ -380,10 +409,12 @@ follows: or c Ret causes Valgrind not to start GDB, and not to ask again.

- --gdb-attach=yes conflicts with - --trace-children=yes. You can't use them - together. Valgrind refuses to start up in this situation. -

+ --gdb-attach=yes conflicts with + --trace-children=yes. You can't use them together. + Valgrind refuses to start up in this situation. 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.

  • --partial-loads-ok=yes [the default]
    --partial-loads-ok=no @@ -411,16 +442,25 @@ follows: 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. Valgrind snapshots dated 17 Feb 2002 and later are + these areas. +

    + Valgrind snapshots dated 17 Feb 2002 and later are cleverer about this problem, and you should no longer need to - use this flag. + use this flag. To put it bluntly, if you do need to use this + flag, your program violates the ANSI C semantics defined for + malloc and free, even if it appears to + work correctly, and you should fix it, at least if you hope for + maximum portability.


  • --trace-children=no [the default]
    --trace-children=yes

    When enabled, Valgrind will trace into child processes. This is confusing and usually not what you want, so is disabled by - default.


    • + default. As of 1 May 2002, tracing into a child process from a + parent which uses libpthread.so is probably broken + and is likely to cause breakage. Please report any such + problems to me.

  • --freelist-vol=<number> [default: 1000000]

    When the client program releases memory using free (in C) or @@ -451,41 +491,41 @@ follows: and ask the shell to route file descriptor 9 to "logfile".


    • -

  • --suppressions=<filename> [default: - /installation/directory/redhat72.supp]

    Specifies an extra +

  • --suppressions=<filename> + [default: $PREFIX/lib/valgrind/default.supp] +

    Specifies an extra file from which to read descriptions of errors to suppress. You may use as many extra suppressions files as you like.


  • --leak-check=no [default]
    - --leak-check=yes + --leak-check=yes

    When enabled, search for memory leaks when the client program finishes. A memory leak means a malloc'd block, which has not yet been free'd, but to which no pointer can be found. Such a block can never be free'd by the program, since no pointer to it - exists. Leak checking is disabled by default - because it tends to generate dozens of error messages. -


    • + exists. Leak checking is disabled by default because it tends + to generate dozens of error messages.

  • --show-reachable=no [default]
    - --show-reachable=yes

    When disabled, the memory - leak detector only shows blocks for which it cannot find a - pointer to at all, or it can only find a pointer to the middle - of. These blocks are prime candidates for memory leaks. When - enabled, the leak detector also reports on blocks which it could - find a pointer to. Your program could, at least in principle, - have freed such blocks before exit. Contrast this to blocks for - which no pointer, or only an interior pointer could be found: - they are more likely to indicate memory leaks, because - you do not actually have a pointer to the start of the block - which you can hand to free(), even if you wanted to. -


    • + --show-reachable=yes +

    When disabled, the memory leak detector only shows blocks for + which it cannot find a pointer to at all, or it can only find a + pointer to the middle of. These blocks are prime candidates for + memory leaks. When enabled, the leak detector also reports on + blocks which it could find a pointer to. Your program could, at + least in principle, have freed such blocks before exit. + Contrast this to blocks for which no pointer, or only an + interior pointer could be found: they are more likely to + indicate memory leaks, because you do not actually have a + pointer to the start of the block which you can hand to + free, even if you wanted to.

  • --leak-resolution=low [default]
    --leak-resolution=med
    --leak-resolution=high

    When doing leak checking, determines how willing Valgrind is - to consider different backtraces the same. When set to + to consider different backtraces to be the same. When set to low, the default, only the first two entries need match. When med, four entries have to match. When high, all entries need to match. @@ -499,7 +539,7 @@ follows:

    Note that the --leak-resolution= setting does not affect Valgrind's ability to find leaks. It only changes how - the results are presented to you. + the results are presented.


  • --workaround-gcc296-bugs=no [default]
    @@ -514,7 +554,9 @@ follows: gcc/g++ which works properly; 2.95.3 seems to be a good choice.

    Unfortunately (27 Feb 02) it looks like g++ 3.0.4 is similarly - buggy, so you may need to issue this flag if you use 3.0.4. + buggy, so you may need to issue this flag if you use 3.0.4. A + while later (early Apr 02) this is confirmed as a scheduling bug + in g++-3.0.4.


  • --cachesim=no [default]
    @@ -595,13 +637,13 @@ shouldn't need to use them in the normal run of things. Nevertheless:

    • -

  • --dump-error=<number> - [default: inactive] +
  • --dump-error=<number> [default: inactive]

    After the program has exited, show gory details of the translation of the basic block containing the <number>'th - error context. When used with --single-step=yes, - can show the - exact x86 instruction causing an error.


    • + error context. When used with --single-step=yes, + can show the exact x86 instruction causing an error. This is + all fairly dodgy and doesn't work at all if threads are + involved.

  • --smc-check=none
    @@ -613,7 +655,15 @@ shouldn't need to use them in the normal run of things. Nevertheless: resulting from moves from integer registers to memory are checked. When "all", all memory writes are checked, even those with which are no sane program would generate code -- for - example, floating-point writes.
    • + example, floating-point writes. +

    + NOTE that this is all a bit bogus. This mechanism has never + been enabled in any snapshot of Valgrind which was made + available to the general public, because the extra checks reduce + performance, increase complexity, and I have yet to come across + any programs which actually use self-modifying code. I think + the flag is ignored. + @@ -632,12 +682,12 @@ precise behaviour of the error-checking machinery is described in

    2.6.1  Illegal read / Illegal write errors

    For example: 
    -  ==30975== Invalid read of size 4
-  ==30975==    at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
-  ==30975==    by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
-  ==30975==    Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
+  Invalid read of size 4
+     at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
+     by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
+     Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd

    This happens when your program reads or writes memory at a place @@ -658,7 +708,8 @@ fact, and also where the block was malloc'd.

    In this example, Valgrind can't identify the address. Actually the address is on the stack, but, for some reason, this is not a valid stack address -- it is below the stack pointer, %esp, and that isn't -allowed. +allowed. In this particular case it's probably caused by gcc +generating invalid code, a known bug in various flavours of gcc.

    Note that Valgrind only tells you that your program is about to access memory at an illegal address. It can't stop the access from @@ -672,11 +723,11 @@ non-fatal, and the program stays alive.

    2.6.2  Use of uninitialised values

    For example: 
    -  ==19146== Conditional jump or move depends on uninitialised value(s)
-  ==19146==    at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
-  ==19146==    by 0x402E8476: _IO_printf (printf.c:36)
-  ==19146==    by 0x8048472: main (tests/manuel1.c:8)
-  ==19146==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+  Conditional jump or move depends on uninitialised value(s)
+     at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
+     by 0x402E8476: _IO_printf (printf.c:36)
+     by 0x8048472: main (tests/manuel1.c:8)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)

    An uninitialised-value use error is reported when your program uses @@ -697,11 +748,10 @@ junk (uninitialised) data to its heart's content. Valgrind observes this and keeps track of the data, but does not complain. A complaint is issued only when your program attempts to make use of uninitialised data. In this example, x is uninitialised. Valgrind observes the -value being passed to _IO_printf and thence to -_IO_vfprintf, but makes no comment. However, -_IO_vfprintf has to examine the value of x -so it can turn it into the corresponding ASCII string, and it is at -this point that Valgrind complains. +value being passed to _IO_printf and thence to _IO_vfprintf, but makes +no comment. However, _IO_vfprintf has to examine the value of x so it +can turn it into the corresponding ASCII string, and it is at this +point that Valgrind complains.

    Sources of uninitialised data tend to be:

    @@ -1450,7 +1622,7 @@ The following list of limitations seems depressingly long. However, most programs actually work fine.

    Valgrind will run x86-GNU/Linux ELF dynamically linked binaries, on -a kernel 2.4.X system, subject to the following constraints: +a kernel 2.2.X or 2.4.X system, subject to the following constraints:

    • No MMX, SSE, SSE2, 3DNow instructions. If the translator @@ -1462,11 +1634,13 @@ a kernel 2.4.X system, subject to the following constraints: the 486 instruction set.

      • -

    • Multithreaded programs are not supported, since I haven't yet - figured out how to do this. To be more specific, it is the - "clone" system call which is not supported. A program calls - "clone" to create threads. Valgrind will abort if this - happens.
      • +
    • 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 libpthread.so, so that Valgrind can + substitute its own implementation at program startup time. If + you're statically linked against it, things will fail + badly.

    • Valgrind assumes that the floating point registers are not used @@ -1491,8 +1665,9 @@ a kernel 2.4.X system, subject to the following constraints: possible.

      • -

    • I have no idea what happens if programs try to handle signals on - an alternate stack (sigaltstack). YMMV.

      • +
    • Programs which try to handle signals on + an alternate stack (sigaltstack) are not supported, although + they could be, with a bit of effort.

    • Programs which switch stacks are not well handled. Valgrind @@ -1501,7 +1676,8 @@ a kernel 2.4.X system, subject to the following constraints: 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.

      • + differently. 1 May 02: this probably interacts badly with the + new pthread support. I haven't checked properly.

    • x86 instructions, and system calls, have been implemented on @@ -1527,50 +1703,30 @@ a kernel 2.4.X system, subject to the following constraints: cause is that Valgrind dynamically translates the original executable and never throws any translation away, except in those rare cases where self-modifying code is detected. - Translated, instrumented code is 8-12 times larger than the + Translated, instrumented code is 12-14 times larger than the original (!) so you can easily end up with 15+ MB of - translations when running (eg) a web browser. There's not a lot - you can do about this -- use Valgrind on a fast machine with a lot - of memory and swap space. At some point I may implement a LRU - caching scheme for translations, so as to bound the maximum - amount of memory devoted to them, to say 8 or 16 MB.
      • + translations when running (eg) a web browser. +
    Programs which are known not to work are:
      -
    • Netscape 4.76 works pretty well on some platforms -- quite - nicely on my AMD K6-III (400 MHz). I can surf, do mail, etc, no - problem. On other platforms is has been observed to crash - during startup. Despite much investigation I can't figure out - why.

      • -

      - -

    • kpackage (a KDE front end to rpm) dies because the CPUID - instruction is unimplemented. Easy to fix.

      • -

      - -

    • knode (a KDE newsreader) tries to do multithreaded things, and - fails.

      • -

      -

    • 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.

      • -

      - -

    • Gimp and Gnome and GTK-based apps die early on because - of unimplemented system call wrappers. (I'm a KDE user :) - This wouldn't be hard to fix. -

      • -

      - -

    • As a consequence of me being a KDE user, almost all KDE apps - work ok -- except those which are multithreaded. -

      • -

      + Valgrind. Emacs works fine if you build it to use the standard + malloc/free routines.
      +

      +

    • Mozilla 1.0RC1 crashes because it jumps to location zero: + Jump to the invalid address stated on the next + line. Other people have reported the same thing. + Despite considerable effort in tracking this down, I cannot + figure out what's going on. If you have a program which does + this, is small enough that I have half a hope of making sense of + it, and is open-source (or at least you'd be happy for me to + look at), I'd be very grateful to have it.
    diff --git a/cachegrind/docs/nav.html b/cachegrind/docs/nav.html index 686ac2bde8..ad920ad443 100644 --- a/cachegrind/docs/nav.html +++ b/cachegrind/docs/nav.html @@ -41,8 +41,10 @@ 2.5 Command-line flags
    2.6 Explanation of error messages
    2.7 Writing suppressions files
    - 2.8 Building and installing
    - 2.9 If you have problems + 2.8 The Client Request mechanism
    + 2.9 Support for POSIX pthreads
    + 2.10 Building and installing
    + 2.11 If you have problems

    3 Details of the checking machinery
    3.1 Valid-value (V) bits
    @@ -62,7 +64,9 @@

    6 An example

    - 7 The design and implementation of Valgrind
    + 7 Cache profiling +

    + 8 The design and implementation of Valgrind
    diff --git a/coregrind/docs/manual.html b/coregrind/docs/manual.html index daaa1535d1..db1d28326f 100644 --- a/coregrind/docs/manual.html +++ b/coregrind/docs/manual.html @@ -24,8 +24,8 @@   -

    Valgrind, snapshot 20020324

    -
    This manual was minimally updated on 20020415
    +

    Valgrind, snapshot 20020501

    +
    This manual was majorly updated on 20020501

    @@ -57,8 +57,10 @@ Linux-x86 executables. 2.5  Command-line flags
    2.6  Explaination of error messages
    2.7  Writing suppressions files
    - 2.8  Building and installing
    - 2.9  If you have problems
    + 2.8  The Client Request mechanism
    + 2.9  Support for POSIX pthreads
    + 2.10  Building and installing
    + 2.11  If you have problems

    3  Details of the checking machinery

    3.1  Valid-value (V) bits
    @@ -112,18 +114,12 @@ 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 I have chosen at the outset to concentrate on what I believe to be a widely used platform: Red Hat -Linux 7.2, on x86s. I believe that it will work without significant -difficulty on other x86 GNU/Linux systems which use the 2.4 kernel and -GNU libc 2.2.X, for example SuSE 7.1 and Mandrake 8.0. Red Hat 6.2 is -also supported. It has worked in the past, and probably still does, -on RedHat 7.1 and 6.2. Note that I haven't compiled it on RedHat 7.1 -and 6.2 for a while, so they may no longer work now. -

    -(Early Feb 02: after feedback from the KDE people it also works better -on other Linuxes). -

    -At some point in the past, Valgrind has also worked on Red Hat 6.2 -(x86), thanks to the efforts of Rob Noble. +Linux 7.2, on x86s. Valgrind uses the standard Unix +./configure, make, make install +mechanism, and I have attempted to ensure that it works on machines +with kernel 2.2 or 2.4 and glibc 2.1.X or 2.2.X. This should cover +the vast majority of modern Linux installations. +

    Valgrind is licensed under the GNU General Public License, version @@ -148,26 +144,27 @@ checks every memory access. All detected errors are written to a log. When the program finishes, Valgrind searches for and reports on leaked memory. -

    You can run pretty much any dynamically linked ELF x86 executable using -Valgrind. Programs run 25 to 50 times slower, and take a lot more -memory, than they usually would. It works well enough to run large -programs. For example, the Konqueror web browser from the KDE Desktop -Environment, version 2.1.1, runs slowly but usably on Valgrind. +

    You can run pretty much any dynamically linked ELF x86 executable +using Valgrind. Programs run 25 to 50 times slower, and take a lot +more memory, than they usually would. It works well enough to run +large programs. For example, the Konqueror web browser from the KDE +Desktop Environment, version 3.0, runs slowly but usably on Valgrind.

    Valgrind simulates every single instruction your program executes. Because of this, it finds errors not only in your application but also -in all supporting dynamically-linked (.so-format) libraries, including -the GNU C library, the X client libraries, Qt, if you work with KDE, and -so on. That often includes libraries, for example the GNU C library, -which contain memory access violations, but which you cannot or do not -want to fix. +in all supporting dynamically-linked (.so-format) +libraries, including the GNU C library, the X client libraries, Qt, if +you work with KDE, and so on. That often includes libraries, for +example the GNU C library, which contain memory access violations, but +which you cannot or do not want to fix.

    Rather than swamping you with errors in which you are not interested, Valgrind allows you to selectively suppress errors, by recording them in a suppressions file which is read when Valgrind -starts up. As supplied, Valgrind comes with a suppressions file -designed to give reasonable behaviour on Red Hat 7.2 (also 7.1 and -6.2) when running text-only and simple X applications. +starts up. The build mechanism attempts to select suppressions which +give reasonable behaviour for the libc and XFree86 versions detected +on your machine. +

    Section 6 shows an example of use.

    @@ -185,9 +182,25 @@ debugging info enabled (the -g flag). 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. +debugger. -

    Then just run your application, but place the word +

    +A plausible compromise is to use -g -O. +Optimisation levels above -O have been observed, on very +rare occasions, to cause gcc to generate code which fools Valgrind's +error tracking machinery into wrongly reporting uninitialised value +errors. -O gets you the vast majority of the benefits of +higher optimisation levels anyway, so you don't lose much there. + +

    +Note that as of 1 May 2002 Valgrind does not understand the DWARF +debugging format, which is unfortunate since the upcoming gcc-3.1 uses +it by default. Valgrind only knows about the older "stabs" format. +If you use gcc-3.1 or above, you can still ask for stabs-format debug +info by passing -gstabs to gcc. + +

    +Then just run your application, but place the word valgrind in front of your usual command-line invokation. Note that you should run the real (machine-code) executable here. If your application is started by, for example, a shell or perl script, @@ -195,7 +208,7 @@ 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 /bin/sh, /usr/bin/perl, or whatever interpreter you're using. -This almost certainly isn't what you want and can be hugely confusing. +This almost certainly isn't what you want and can be confusing.

    2.2  The commentary

    @@ -265,6 +278,17 @@ later uses them, will generate several error messages. The first such error message may well give the most direct clue to the root cause of the problem. +

    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 vg_include.h and can be increased +if necessary. +

    2.4  Suppressing errors

    @@ -272,14 +296,15 @@ Valgrind detects 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. By default -this file is redhat72.supp, located in the Valgrind -installation directory. +Valgrind reads a list of errors to suppress at startup. +A default suppression file is cooked up by the +./configure script. -

    You can modify and add to the suppressions file at your leisure, or -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. +

    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.

    Each error to be suppressed is described very specifically, to minimise the possibility that a suppression-directive inadvertantly @@ -305,6 +330,10 @@ You invoke Valgrind like this: valgrind [options-for-Valgrind] your-prog [options for your-prog] +

    Note that Valgrind also reads options from the environment variable +$VALGRIND, and processes them before the command-line +options. +

    Valgrind's default settings succeed in giving reasonable behaviour in most cases. Available options, in no particular order, are as follows: @@ -380,10 +409,12 @@ follows: or c Ret causes Valgrind not to start GDB, and not to ask again.

    - --gdb-attach=yes conflicts with - --trace-children=yes. You can't use them - together. Valgrind refuses to start up in this situation. -

    + --gdb-attach=yes conflicts with + --trace-children=yes. You can't use them together. + Valgrind refuses to start up in this situation. 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.

  • --partial-loads-ok=yes [the default]
    --partial-loads-ok=no @@ -411,16 +442,25 @@ follows: 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. Valgrind snapshots dated 17 Feb 2002 and later are + these areas. +

    + Valgrind snapshots dated 17 Feb 2002 and later are cleverer about this problem, and you should no longer need to - use this flag. + use this flag. To put it bluntly, if you do need to use this + flag, your program violates the ANSI C semantics defined for + malloc and free, even if it appears to + work correctly, and you should fix it, at least if you hope for + maximum portability.


  • --trace-children=no [the default]
    --trace-children=yes

    When enabled, Valgrind will trace into child processes. This is confusing and usually not what you want, so is disabled by - default.


    • + default. As of 1 May 2002, tracing into a child process from a + parent which uses libpthread.so is probably broken + and is likely to cause breakage. Please report any such + problems to me.

  • --freelist-vol=<number> [default: 1000000]

    When the client program releases memory using free (in C) or @@ -451,41 +491,41 @@ follows: and ask the shell to route file descriptor 9 to "logfile".


    • -

  • --suppressions=<filename> [default: - /installation/directory/redhat72.supp]

    Specifies an extra +

  • --suppressions=<filename> + [default: $PREFIX/lib/valgrind/default.supp] +

    Specifies an extra file from which to read descriptions of errors to suppress. You may use as many extra suppressions files as you like.


  • --leak-check=no [default]
    - --leak-check=yes + --leak-check=yes

    When enabled, search for memory leaks when the client program finishes. A memory leak means a malloc'd block, which has not yet been free'd, but to which no pointer can be found. Such a block can never be free'd by the program, since no pointer to it - exists. Leak checking is disabled by default - because it tends to generate dozens of error messages. -


    • + exists. Leak checking is disabled by default because it tends + to generate dozens of error messages.

  • --show-reachable=no [default]
    - --show-reachable=yes

    When disabled, the memory - leak detector only shows blocks for which it cannot find a - pointer to at all, or it can only find a pointer to the middle - of. These blocks are prime candidates for memory leaks. When - enabled, the leak detector also reports on blocks which it could - find a pointer to. Your program could, at least in principle, - have freed such blocks before exit. Contrast this to blocks for - which no pointer, or only an interior pointer could be found: - they are more likely to indicate memory leaks, because - you do not actually have a pointer to the start of the block - which you can hand to free(), even if you wanted to. -


    • + --show-reachable=yes +

    When disabled, the memory leak detector only shows blocks for + which it cannot find a pointer to at all, or it can only find a + pointer to the middle of. These blocks are prime candidates for + memory leaks. When enabled, the leak detector also reports on + blocks which it could find a pointer to. Your program could, at + least in principle, have freed such blocks before exit. + Contrast this to blocks for which no pointer, or only an + interior pointer could be found: they are more likely to + indicate memory leaks, because you do not actually have a + pointer to the start of the block which you can hand to + free, even if you wanted to.

  • --leak-resolution=low [default]
    --leak-resolution=med
    --leak-resolution=high

    When doing leak checking, determines how willing Valgrind is - to consider different backtraces the same. When set to + to consider different backtraces to be the same. When set to low, the default, only the first two entries need match. When med, four entries have to match. When high, all entries need to match. @@ -499,7 +539,7 @@ follows:

    Note that the --leak-resolution= setting does not affect Valgrind's ability to find leaks. It only changes how - the results are presented to you. + the results are presented.


  • --workaround-gcc296-bugs=no [default]
    @@ -514,7 +554,9 @@ follows: gcc/g++ which works properly; 2.95.3 seems to be a good choice.

    Unfortunately (27 Feb 02) it looks like g++ 3.0.4 is similarly - buggy, so you may need to issue this flag if you use 3.0.4. + buggy, so you may need to issue this flag if you use 3.0.4. A + while later (early Apr 02) this is confirmed as a scheduling bug + in g++-3.0.4.


  • --cachesim=no [default]
    @@ -595,13 +637,13 @@ shouldn't need to use them in the normal run of things. Nevertheless:

    • -

  • --dump-error=<number> - [default: inactive] +
  • --dump-error=<number> [default: inactive]

    After the program has exited, show gory details of the translation of the basic block containing the <number>'th - error context. When used with --single-step=yes, - can show the - exact x86 instruction causing an error.


    • + error context. When used with --single-step=yes, + can show the exact x86 instruction causing an error. This is + all fairly dodgy and doesn't work at all if threads are + involved.

  • --smc-check=none
    @@ -613,7 +655,15 @@ shouldn't need to use them in the normal run of things. Nevertheless: resulting from moves from integer registers to memory are checked. When "all", all memory writes are checked, even those with which are no sane program would generate code -- for - example, floating-point writes.
    • + example, floating-point writes. +

    + NOTE that this is all a bit bogus. This mechanism has never + been enabled in any snapshot of Valgrind which was made + available to the general public, because the extra checks reduce + performance, increase complexity, and I have yet to come across + any programs which actually use self-modifying code. I think + the flag is ignored. + @@ -632,12 +682,12 @@ precise behaviour of the error-checking machinery is described in

    2.6.1  Illegal read / Illegal write errors

    For example: 
    -  ==30975== Invalid read of size 4
-  ==30975==    at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
-  ==30975==    by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
-  ==30975==    Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
+  Invalid read of size 4
+     at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
+     by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
+     Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd

    This happens when your program reads or writes memory at a place @@ -658,7 +708,8 @@ fact, and also where the block was malloc'd.

    In this example, Valgrind can't identify the address. Actually the address is on the stack, but, for some reason, this is not a valid stack address -- it is below the stack pointer, %esp, and that isn't -allowed. +allowed. In this particular case it's probably caused by gcc +generating invalid code, a known bug in various flavours of gcc.

    Note that Valgrind only tells you that your program is about to access memory at an illegal address. It can't stop the access from @@ -672,11 +723,11 @@ non-fatal, and the program stays alive.

    2.6.2  Use of uninitialised values

    For example: 
    -  ==19146== Conditional jump or move depends on uninitialised value(s)
-  ==19146==    at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
-  ==19146==    by 0x402E8476: _IO_printf (printf.c:36)
-  ==19146==    by 0x8048472: main (tests/manuel1.c:8)
-  ==19146==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+  Conditional jump or move depends on uninitialised value(s)
+     at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
+     by 0x402E8476: _IO_printf (printf.c:36)
+     by 0x8048472: main (tests/manuel1.c:8)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)

    An uninitialised-value use error is reported when your program uses @@ -697,11 +748,10 @@ junk (uninitialised) data to its heart's content. Valgrind observes this and keeps track of the data, but does not complain. A complaint is issued only when your program attempts to make use of uninitialised data. In this example, x is uninitialised. Valgrind observes the -value being passed to _IO_printf and thence to -_IO_vfprintf, but makes no comment. However, -_IO_vfprintf has to examine the value of x -so it can turn it into the corresponding ASCII string, and it is at -this point that Valgrind complains. +value being passed to _IO_printf and thence to _IO_vfprintf, but makes +no comment. However, _IO_vfprintf has to examine the value of x so it +can turn it into the corresponding ASCII string, and it is at this +point that Valgrind complains.

    Sources of uninitialised data tend to be:

      @@ -720,16 +770,16 @@ this point that Valgrind complains.

      2.6.3  Illegal frees

      For example: 
      -  ==7593== Invalid free()
-  ==7593==    at 0x4004FFDF: free (ut_clientmalloc.c:577)
-  ==7593==    by 0x80484C7: main (tests/doublefree.c:10)
-  ==7593==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==7593==    by 0x80483B1: (within tests/doublefree)
-  ==7593==    Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
-  ==7593==    at 0x4004FFDF: free (ut_clientmalloc.c:577)
-  ==7593==    by 0x80484C7: main (tests/doublefree.c:10)
-  ==7593==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==7593==    by 0x80483B1: (within tests/doublefree)
+  Invalid free()
+     at 0x4004FFDF: free (ut_clientmalloc.c:577)
+     by 0x80484C7: main (tests/doublefree.c:10)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/doublefree)
+     Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
+     at 0x4004FFDF: free (ut_clientmalloc.c:577)
+     by 0x80484C7: main (tests/doublefree.c:10)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/doublefree)

      Valgrind keeps track of the blocks allocated by your program with malloc/new, so it can know exactly whether or not the argument to @@ -740,7 +790,44 @@ here, the address is one which has previously been freed, you wil be told that -- making duplicate frees of the same block easy to spot. -

      2.6.4  Passing system call parameters with inadequate +

      2.6.4  When a block is freed with an inappropriate +deallocation function

      +For example: +
      +  Mismatched free() / delete / delete []
+     at 0x40303847: DeviceContextImpl::~DeviceContextImpl(void)
+     by 0x45149BCB: nsDeviceContextGTK::~nsDeviceContextGTK(void)
+     by 0x4030341A: DeviceContextImpl::Release(void)
+     by 0x460C0CAC: nsBaseWidget::OnDestroy(void)
+     Address 0x41C11A7C is 0 bytes inside a block of size 120 alloc'd
+     at 0x40040BEC: malloc (vg_clientfuncs.c:100)
+     by 0x4516DAAC: ??? (../../gcc-2.95.3/gcc/cp/new1.cc:78)
+     by 0x4515FA11: nsDeviceContextGTKConstructor(nsISupports *, ...
+     by 0x40553ABB: nsGenericFactory::CreateInstance(nsISupports *, ...
+
      +The following was told to me be the KDE 3 developers. I didn't know +any of it myself. They also implemented the check itself. +

      +In C++ it's important to deallocate memory in a way compatible with +how it was allocated. The deal is: +

        +
      • If allocated with malloc, calloc, + realloc, valloc or + memalign, you must deallocate with free. +
      • If allocated with new [], you must deallocate with + delete []. +
      • If allocated with new, you must deallocate with + delete. +
      +The worst thing is that on Linux apparently it doesn't matter if you +do muddle these up, and it all seems to work ok, but the same program +may then crash on a different platform, Solaris for example. So it's +best to fix it properly. According to the KDE folks "it's amazing how +many C++ programmers don't know this". + + + +

      2.6.5  Passing system call parameters with inadequate read/write permissions

      Valgrind checks all parameters to system calls. If a system call @@ -766,23 +853,23 @@ system call.

      You get this complaint ... 

      -  ==8230== Syscall param write(buf) lacks read permissions
-  ==8230==    at 0x4035E072: __libc_write
-  ==8230==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==8230==    by 0x80483B1: (within tests/badwrite)
-  ==8230==    by <bogus frame pointer> ???
-  ==8230==    Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
-  ==8230==    at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
-  ==8230==    by 0x80484A0: main (tests/badwrite.c:6)
-  ==8230==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==8230==    by 0x80483B1: (within tests/badwrite)
+  Syscall param write(buf) contains uninitialised or unaddressable byte(s)
+     at 0x4035E072: __libc_write
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/badwrite)
+     by <bogus frame pointer> ???
+     Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
+     at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
+     by 0x80484A0: main (tests/badwrite.c:6)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/badwrite)

      ... because the program has tried to write uninitialised junk from the malloc'd block to the standard output. -

      2.6.5  Warning messages you might see

      +

      2.6.6  Warning messages you might see

      Most of these only appear if you run in verbose mode (enabled by -v): @@ -799,11 +886,11 @@ Most of these only appear if you run in verbose mode (enabled by appearance of new errors after the first 50. The 50 constant can be changed by recompiling Valgrind.

      -

    • More than 500 errors detected. I'm not reporting any more. +
    • More than 300 errors detected. I'm not reporting any more. Final error counts may be inaccurate. Go fix your program!
      - After 500 different errors have been detected, Valgrind ignores + 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 @@ -875,7 +962,7 @@ or another, you don't want Valgrind to tell you about. Usually the reason is that the system libraries are buggy but unfixable, at least within the scope of the current debugging session. Multiple suppresions files are allowed. By default, Valgrind uses -linux24.supp in the directory where it is installed. +$PREFIX/lib/valgrind/default.supp.

      You can ask to add suppressions from another file, by specifying @@ -977,28 +1064,13 @@ you can freely mix the obj: and fun: styles of description within a single suppression record. - -

      2.8  Building and installing

      -At the moment, very rudimentary. - -

      The tarball is set up for a standard Red Hat 7.1 (6.2) machine. To -build, just do "make". No configure script, no autoconf, no nothing. - -

      The files needed for installation are: valgrind.so, valgring.so, -valgrind, VERSION, redhat72.supp (or redhat62.supp). You can copy -these to any directory you like. However, you then need to edit the -shell script "valgrind". On line 4, set the environment variable -VALGRIND to point to the directory you have copied the -installation into. - - - -

      2.9  The Client Request mechanism

      + +

      2.8  The Client Request mechanism

      Valgrind has a trapdoor mechanism via which the client program can pass all manner of requests and queries to Valgrind. Internally, this -is used extensively to make malloc, free, signals, etc, work, although -you don't see that. +is used extensively to make malloc, free, signals, threads, etc, work, +although you don't see that.

      For your convenience, a subset of these so-called client requests is provided to allow you to tell Valgrind facts about the behaviour of @@ -1012,6 +1084,8 @@ make this work. The macros therein 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.

      A brief description of the available macros:

        @@ -1070,14 +1144,107 @@ A brief description of the available macros: automatically discards this information when the stack retreats past such blocks. Beware: hacky and flaky, and probably interacts badly with the new pthread support. +

        +

      • RUNNING_ON_VALGRIND: returns 1 if running on + Valgrind, 0 if running on the real CPU. +

        +

      • VALGRIND_DO_LEAK_CHECK: run the memory leak detector + right now. Returns no value. I guess this could be used to + incrementally check for leaks between arbitrary places in the + program's execution. Warning: not properly tested!
      -

      • + +

      2.9  Support for POSIX Pthreads

      + +As of late April 02, Valgrind supports programs which use POSIX +pthreads. Doing this has proved technically challenging and is still +in progress, but it works well enough, as of 1 May 02, for significant +threaded applications to work. +

      +It works as follows: threaded apps are (dynamically) linked against +libpthread.so. Usually this is the one installed with +your Linux distribution. Valgrind, however, supplies its own +libpthread.so and automatically connects your program to +it instead. +

      +The fake libpthread.so 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. +

      +Valgrind schedules your threads in a round-robin fashion, with all +threads having equal priority. It switches threads every 20000 basic +blocks (typically around 120000 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. +

      +The current (1 May 02) state of pthread support is as follows. Please +note that things are advancing rapidly, so the situation may have +improved by the time you read this -- check the web site for further +updates. +

        +
      • Mutexes, condition variables, thread-specific data and + pthread_once currently work. +

        +

      • Various attribute-like calls are handled but ignored. + You get a warning message. +

        +

      • The main big omission is proper cleanup support for cancellation. + pthread_cancel works, but instantly nukes the target + thread without giving it any chance to clean up. Also, when a + thread exits, it does not run any cleanup handlers. +

        +

      • Currently the following syscalls are thread-safe (nonblocking): + write read nanosleep + sleep select and poll. +

        +

      • The POSIX requirement that each thread have its own + signal-blocking mask is not done; the signal handling mechanism is + thread-unaware and all signals are delivered to the main thread, + antidisirregardless. +
      + + +As of 1 May 02, the following 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. +

      +Mozilla 1.0RC1 crashes because it jumps to location zero: Jump +to the invalid address stated on the next line. Other people +have reported the same thing. Despite considerable effort in tracking +this down, I cannot figure out what's going on. If you have a program +which does this, is small enough that I have half a hope of making +sense of it, and is open-source (or at least you'd be happy for me to +look at), I'd be very grateful to have it. +

      +On the other hand, I have received mail from at least one person +who appears to be successful in running CVS builds of Mozilla on +Valgrind. + + + + +

      2.10  Building and installing

      + +We now use the standard Unix ./configure, +make, make install mechanism, and I have +attempted to ensure that it works on machines with kernel 2.2 or 2.4 +and glibc 2.1.X or 2.2.X. I don't think there is much else to say. +There are no options apart from the usual --prefix that +you should give to ./configure. +

      +Let me know if you have build problems. + + -

      2.10  If you have problems

      +

      2.11  If you have problems

      Mail me (jseward@acm.org).

      See Section 4 for the known limitations of @@ -1115,7 +1282,7 @@ which says whether or not the accompanying bit has a legitimate value. In the discussions which follow, this bit is referred to as the V (valid-value) bit. -

      Each byte in the system therefore has a 8 V bits which accompanies +

      Each byte in the system therefore has a 8 V bits which follow it wherever it goes. For example, when the CPU loads a word-size item (4 bytes) from memory, it also loads the corresponding 32 V bits from a bitmap which stores the V bits for the process' entire address @@ -1125,7 +1292,8 @@ stored back in the V-bit bitmap.

      In short, each bit in the system has an associated V bit, which follows it around everywhere, even inside the CPU. Yes, the CPU's -(integer) registers have their own V bit vectors. +(integer and %eflags) registers have their own V bit +vectors.

      Copying values around does not cause Valgrind to check for, or report on, errors. However, when a value is used in a way which might @@ -1166,7 +1334,7 @@ used to generate a memory address, and where control flow decision needs to be made. Also, when a system call is detected, valgrind checks definedness of parameters as required. -

      If a check should detect undefinedness, and error message is +

      If a check should detect undefinedness, an error message is issued. The resulting value is subsequently regarded as well-defined. To do otherwise would give long chains of error messages. In effect, we say that undefined values are non-infectious. @@ -1264,6 +1432,10 @@ themselves do not change the A bits, only consult them. example, mmap() magically makes files appear in the process's address space, so the A bits must be updated if mmap() succeeds.
      +

      + +

    • Optionally, your program can tell Valgrind about such changes + explicitly, using the client request mechanism described above.
    @@ -1450,7 +1622,7 @@ The following list of limitations seems depressingly long. However, most programs actually work fine.

    Valgrind will run x86-GNU/Linux ELF dynamically linked binaries, on -a kernel 2.4.X system, subject to the following constraints: +a kernel 2.2.X or 2.4.X system, subject to the following constraints:

    • No MMX, SSE, SSE2, 3DNow instructions. If the translator @@ -1462,11 +1634,13 @@ a kernel 2.4.X system, subject to the following constraints: the 486 instruction set.

      • -

    • Multithreaded programs are not supported, since I haven't yet - figured out how to do this. To be more specific, it is the - "clone" system call which is not supported. A program calls - "clone" to create threads. Valgrind will abort if this - happens.
      • +
    • 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 libpthread.so, so that Valgrind can + substitute its own implementation at program startup time. If + you're statically linked against it, things will fail + badly.

    • Valgrind assumes that the floating point registers are not used @@ -1491,8 +1665,9 @@ a kernel 2.4.X system, subject to the following constraints: possible.

      • -

    • I have no idea what happens if programs try to handle signals on - an alternate stack (sigaltstack). YMMV.

      • +
    • Programs which try to handle signals on + an alternate stack (sigaltstack) are not supported, although + they could be, with a bit of effort.

    • Programs which switch stacks are not well handled. Valgrind @@ -1501,7 +1676,8 @@ a kernel 2.4.X system, subject to the following constraints: 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.

      • + differently. 1 May 02: this probably interacts badly with the + new pthread support. I haven't checked properly.

    • x86 instructions, and system calls, have been implemented on @@ -1527,50 +1703,30 @@ a kernel 2.4.X system, subject to the following constraints: cause is that Valgrind dynamically translates the original executable and never throws any translation away, except in those rare cases where self-modifying code is detected. - Translated, instrumented code is 8-12 times larger than the + Translated, instrumented code is 12-14 times larger than the original (!) so you can easily end up with 15+ MB of - translations when running (eg) a web browser. There's not a lot - you can do about this -- use Valgrind on a fast machine with a lot - of memory and swap space. At some point I may implement a LRU - caching scheme for translations, so as to bound the maximum - amount of memory devoted to them, to say 8 or 16 MB.
      • + translations when running (eg) a web browser. +
    Programs which are known not to work are:
      -
    • Netscape 4.76 works pretty well on some platforms -- quite - nicely on my AMD K6-III (400 MHz). I can surf, do mail, etc, no - problem. On other platforms is has been observed to crash - during startup. Despite much investigation I can't figure out - why.

      • -

      - -

    • kpackage (a KDE front end to rpm) dies because the CPUID - instruction is unimplemented. Easy to fix.

      • -

      - -

    • knode (a KDE newsreader) tries to do multithreaded things, and - fails.

      • -

      -

    • 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.

      • -

      - -

    • Gimp and Gnome and GTK-based apps die early on because - of unimplemented system call wrappers. (I'm a KDE user :) - This wouldn't be hard to fix. -

      • -

      - -

    • As a consequence of me being a KDE user, almost all KDE apps - work ok -- except those which are multithreaded. -

      • -

      + Valgrind. Emacs works fine if you build it to use the standard + malloc/free routines.
      +

      +

    • Mozilla 1.0RC1 crashes because it jumps to location zero: + Jump to the invalid address stated on the next + line. Other people have reported the same thing. + Despite considerable effort in tracking this down, I cannot + figure out what's going on. If you have a program which does + this, is small enough that I have half a hope of making sense of + it, and is open-source (or at least you'd be happy for me to + look at), I'd be very grateful to have it.
    diff --git a/coregrind/docs/nav.html b/coregrind/docs/nav.html index 686ac2bde8..ad920ad443 100644 --- a/coregrind/docs/nav.html +++ b/coregrind/docs/nav.html @@ -41,8 +41,10 @@ 2.5 Command-line flags
    2.6 Explanation of error messages
    2.7 Writing suppressions files
    - 2.8 Building and installing
    - 2.9 If you have problems + 2.8 The Client Request mechanism
    + 2.9 Support for POSIX pthreads
    + 2.10 Building and installing
    + 2.11 If you have problems

    3 Details of the checking machinery
    3.1 Valid-value (V) bits
    @@ -62,7 +64,9 @@

    6 An example

    - 7 The design and implementation of Valgrind
    + 7 Cache profiling +

    + 8 The design and implementation of Valgrind
    diff --git a/docs/manual.html b/docs/manual.html index daaa1535d1..db1d28326f 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -24,8 +24,8 @@   -

    Valgrind, snapshot 20020324

    -
    This manual was minimally updated on 20020415
    +

    Valgrind, snapshot 20020501

    +
    This manual was majorly updated on 20020501

    @@ -57,8 +57,10 @@ Linux-x86 executables. 2.5  Command-line flags
    2.6  Explaination of error messages
    2.7  Writing suppressions files
    - 2.8  Building and installing
    - 2.9  If you have problems
    + 2.8  The Client Request mechanism
    + 2.9  Support for POSIX pthreads
    + 2.10  Building and installing
    + 2.11  If you have problems

    3  Details of the checking machinery

    3.1  Valid-value (V) bits
    @@ -112,18 +114,12 @@ 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 I have chosen at the outset to concentrate on what I believe to be a widely used platform: Red Hat -Linux 7.2, on x86s. I believe that it will work without significant -difficulty on other x86 GNU/Linux systems which use the 2.4 kernel and -GNU libc 2.2.X, for example SuSE 7.1 and Mandrake 8.0. Red Hat 6.2 is -also supported. It has worked in the past, and probably still does, -on RedHat 7.1 and 6.2. Note that I haven't compiled it on RedHat 7.1 -and 6.2 for a while, so they may no longer work now. -

    -(Early Feb 02: after feedback from the KDE people it also works better -on other Linuxes). -

    -At some point in the past, Valgrind has also worked on Red Hat 6.2 -(x86), thanks to the efforts of Rob Noble. +Linux 7.2, on x86s. Valgrind uses the standard Unix +./configure, make, make install +mechanism, and I have attempted to ensure that it works on machines +with kernel 2.2 or 2.4 and glibc 2.1.X or 2.2.X. This should cover +the vast majority of modern Linux installations. +

    Valgrind is licensed under the GNU General Public License, version @@ -148,26 +144,27 @@ checks every memory access. All detected errors are written to a log. When the program finishes, Valgrind searches for and reports on leaked memory. -

    You can run pretty much any dynamically linked ELF x86 executable using -Valgrind. Programs run 25 to 50 times slower, and take a lot more -memory, than they usually would. It works well enough to run large -programs. For example, the Konqueror web browser from the KDE Desktop -Environment, version 2.1.1, runs slowly but usably on Valgrind. +

    You can run pretty much any dynamically linked ELF x86 executable +using Valgrind. Programs run 25 to 50 times slower, and take a lot +more memory, than they usually would. It works well enough to run +large programs. For example, the Konqueror web browser from the KDE +Desktop Environment, version 3.0, runs slowly but usably on Valgrind.

    Valgrind simulates every single instruction your program executes. Because of this, it finds errors not only in your application but also -in all supporting dynamically-linked (.so-format) libraries, including -the GNU C library, the X client libraries, Qt, if you work with KDE, and -so on. That often includes libraries, for example the GNU C library, -which contain memory access violations, but which you cannot or do not -want to fix. +in all supporting dynamically-linked (.so-format) +libraries, including the GNU C library, the X client libraries, Qt, if +you work with KDE, and so on. That often includes libraries, for +example the GNU C library, which contain memory access violations, but +which you cannot or do not want to fix.

    Rather than swamping you with errors in which you are not interested, Valgrind allows you to selectively suppress errors, by recording them in a suppressions file which is read when Valgrind -starts up. As supplied, Valgrind comes with a suppressions file -designed to give reasonable behaviour on Red Hat 7.2 (also 7.1 and -6.2) when running text-only and simple X applications. +starts up. The build mechanism attempts to select suppressions which +give reasonable behaviour for the libc and XFree86 versions detected +on your machine. +

    Section 6 shows an example of use.

    @@ -185,9 +182,25 @@ debugging info enabled (the -g flag). 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. +debugger. -

    Then just run your application, but place the word +

    +A plausible compromise is to use -g -O. +Optimisation levels above -O have been observed, on very +rare occasions, to cause gcc to generate code which fools Valgrind's +error tracking machinery into wrongly reporting uninitialised value +errors. -O gets you the vast majority of the benefits of +higher optimisation levels anyway, so you don't lose much there. + +

    +Note that as of 1 May 2002 Valgrind does not understand the DWARF +debugging format, which is unfortunate since the upcoming gcc-3.1 uses +it by default. Valgrind only knows about the older "stabs" format. +If you use gcc-3.1 or above, you can still ask for stabs-format debug +info by passing -gstabs to gcc. + +

    +Then just run your application, but place the word valgrind in front of your usual command-line invokation. Note that you should run the real (machine-code) executable here. If your application is started by, for example, a shell or perl script, @@ -195,7 +208,7 @@ 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 /bin/sh, /usr/bin/perl, or whatever interpreter you're using. -This almost certainly isn't what you want and can be hugely confusing. +This almost certainly isn't what you want and can be confusing.

    2.2  The commentary

    @@ -265,6 +278,17 @@ later uses them, will generate several error messages. The first such error message may well give the most direct clue to the root cause of the problem. +

    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 vg_include.h and can be increased +if necessary. +

    2.4  Suppressing errors

    @@ -272,14 +296,15 @@ Valgrind detects 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. By default -this file is redhat72.supp, located in the Valgrind -installation directory. +Valgrind reads a list of errors to suppress at startup. +A default suppression file is cooked up by the +./configure script. -

    You can modify and add to the suppressions file at your leisure, or -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. +

    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.

    Each error to be suppressed is described very specifically, to minimise the possibility that a suppression-directive inadvertantly @@ -305,6 +330,10 @@ You invoke Valgrind like this: valgrind [options-for-Valgrind] your-prog [options for your-prog] +

    Note that Valgrind also reads options from the environment variable +$VALGRIND, and processes them before the command-line +options. +

    Valgrind's default settings succeed in giving reasonable behaviour in most cases. Available options, in no particular order, are as follows: @@ -380,10 +409,12 @@ follows: or c Ret causes Valgrind not to start GDB, and not to ask again.

    - --gdb-attach=yes conflicts with - --trace-children=yes. You can't use them - together. Valgrind refuses to start up in this situation. -

    + --gdb-attach=yes conflicts with + --trace-children=yes. You can't use them together. + Valgrind refuses to start up in this situation. 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.

  • --partial-loads-ok=yes [the default]
    --partial-loads-ok=no @@ -411,16 +442,25 @@ follows: 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. Valgrind snapshots dated 17 Feb 2002 and later are + these areas. +

    + Valgrind snapshots dated 17 Feb 2002 and later are cleverer about this problem, and you should no longer need to - use this flag. + use this flag. To put it bluntly, if you do need to use this + flag, your program violates the ANSI C semantics defined for + malloc and free, even if it appears to + work correctly, and you should fix it, at least if you hope for + maximum portability.


  • --trace-children=no [the default]
    --trace-children=yes

    When enabled, Valgrind will trace into child processes. This is confusing and usually not what you want, so is disabled by - default.


    • + default. As of 1 May 2002, tracing into a child process from a + parent which uses libpthread.so is probably broken + and is likely to cause breakage. Please report any such + problems to me.

  • --freelist-vol=<number> [default: 1000000]

    When the client program releases memory using free (in C) or @@ -451,41 +491,41 @@ follows: and ask the shell to route file descriptor 9 to "logfile".


    • -

  • --suppressions=<filename> [default: - /installation/directory/redhat72.supp]

    Specifies an extra +

  • --suppressions=<filename> + [default: $PREFIX/lib/valgrind/default.supp] +

    Specifies an extra file from which to read descriptions of errors to suppress. You may use as many extra suppressions files as you like.


  • --leak-check=no [default]
    - --leak-check=yes + --leak-check=yes

    When enabled, search for memory leaks when the client program finishes. A memory leak means a malloc'd block, which has not yet been free'd, but to which no pointer can be found. Such a block can never be free'd by the program, since no pointer to it - exists. Leak checking is disabled by default - because it tends to generate dozens of error messages. -


    • + exists. Leak checking is disabled by default because it tends + to generate dozens of error messages.

  • --show-reachable=no [default]
    - --show-reachable=yes

    When disabled, the memory - leak detector only shows blocks for which it cannot find a - pointer to at all, or it can only find a pointer to the middle - of. These blocks are prime candidates for memory leaks. When - enabled, the leak detector also reports on blocks which it could - find a pointer to. Your program could, at least in principle, - have freed such blocks before exit. Contrast this to blocks for - which no pointer, or only an interior pointer could be found: - they are more likely to indicate memory leaks, because - you do not actually have a pointer to the start of the block - which you can hand to free(), even if you wanted to. -


    • + --show-reachable=yes +

    When disabled, the memory leak detector only shows blocks for + which it cannot find a pointer to at all, or it can only find a + pointer to the middle of. These blocks are prime candidates for + memory leaks. When enabled, the leak detector also reports on + blocks which it could find a pointer to. Your program could, at + least in principle, have freed such blocks before exit. + Contrast this to blocks for which no pointer, or only an + interior pointer could be found: they are more likely to + indicate memory leaks, because you do not actually have a + pointer to the start of the block which you can hand to + free, even if you wanted to.

  • --leak-resolution=low [default]
    --leak-resolution=med
    --leak-resolution=high

    When doing leak checking, determines how willing Valgrind is - to consider different backtraces the same. When set to + to consider different backtraces to be the same. When set to low, the default, only the first two entries need match. When med, four entries have to match. When high, all entries need to match. @@ -499,7 +539,7 @@ follows:

    Note that the --leak-resolution= setting does not affect Valgrind's ability to find leaks. It only changes how - the results are presented to you. + the results are presented.


  • --workaround-gcc296-bugs=no [default]
    @@ -514,7 +554,9 @@ follows: gcc/g++ which works properly; 2.95.3 seems to be a good choice.

    Unfortunately (27 Feb 02) it looks like g++ 3.0.4 is similarly - buggy, so you may need to issue this flag if you use 3.0.4. + buggy, so you may need to issue this flag if you use 3.0.4. A + while later (early Apr 02) this is confirmed as a scheduling bug + in g++-3.0.4.


  • --cachesim=no [default]
    @@ -595,13 +637,13 @@ shouldn't need to use them in the normal run of things. Nevertheless:

    • -

  • --dump-error=<number> - [default: inactive] +
  • --dump-error=<number> [default: inactive]

    After the program has exited, show gory details of the translation of the basic block containing the <number>'th - error context. When used with --single-step=yes, - can show the - exact x86 instruction causing an error.


    • + error context. When used with --single-step=yes, + can show the exact x86 instruction causing an error. This is + all fairly dodgy and doesn't work at all if threads are + involved.

  • --smc-check=none
    @@ -613,7 +655,15 @@ shouldn't need to use them in the normal run of things. Nevertheless: resulting from moves from integer registers to memory are checked. When "all", all memory writes are checked, even those with which are no sane program would generate code -- for - example, floating-point writes.
    • + example, floating-point writes. +

    + NOTE that this is all a bit bogus. This mechanism has never + been enabled in any snapshot of Valgrind which was made + available to the general public, because the extra checks reduce + performance, increase complexity, and I have yet to come across + any programs which actually use self-modifying code. I think + the flag is ignored. + @@ -632,12 +682,12 @@ precise behaviour of the error-checking machinery is described in

    2.6.1  Illegal read / Illegal write errors

    For example: 
    -  ==30975== Invalid read of size 4
-  ==30975==    at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
-  ==30975==    by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
-  ==30975==    Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
+  Invalid read of size 4
+     at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
+     by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
+     Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd

    This happens when your program reads or writes memory at a place @@ -658,7 +708,8 @@ fact, and also where the block was malloc'd.

    In this example, Valgrind can't identify the address. Actually the address is on the stack, but, for some reason, this is not a valid stack address -- it is below the stack pointer, %esp, and that isn't -allowed. +allowed. In this particular case it's probably caused by gcc +generating invalid code, a known bug in various flavours of gcc.

    Note that Valgrind only tells you that your program is about to access memory at an illegal address. It can't stop the access from @@ -672,11 +723,11 @@ non-fatal, and the program stays alive.

    2.6.2  Use of uninitialised values

    For example: 
    -  ==19146== Conditional jump or move depends on uninitialised value(s)
-  ==19146==    at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
-  ==19146==    by 0x402E8476: _IO_printf (printf.c:36)
-  ==19146==    by 0x8048472: main (tests/manuel1.c:8)
-  ==19146==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+  Conditional jump or move depends on uninitialised value(s)
+     at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
+     by 0x402E8476: _IO_printf (printf.c:36)
+     by 0x8048472: main (tests/manuel1.c:8)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)

    An uninitialised-value use error is reported when your program uses @@ -697,11 +748,10 @@ junk (uninitialised) data to its heart's content. Valgrind observes this and keeps track of the data, but does not complain. A complaint is issued only when your program attempts to make use of uninitialised data. In this example, x is uninitialised. Valgrind observes the -value being passed to _IO_printf and thence to -_IO_vfprintf, but makes no comment. However, -_IO_vfprintf has to examine the value of x -so it can turn it into the corresponding ASCII string, and it is at -this point that Valgrind complains. +value being passed to _IO_printf and thence to _IO_vfprintf, but makes +no comment. However, _IO_vfprintf has to examine the value of x so it +can turn it into the corresponding ASCII string, and it is at this +point that Valgrind complains.

    Sources of uninitialised data tend to be:

      @@ -720,16 +770,16 @@ this point that Valgrind complains.

      2.6.3  Illegal frees

      For example: 
      -  ==7593== Invalid free()
-  ==7593==    at 0x4004FFDF: free (ut_clientmalloc.c:577)
-  ==7593==    by 0x80484C7: main (tests/doublefree.c:10)
-  ==7593==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==7593==    by 0x80483B1: (within tests/doublefree)
-  ==7593==    Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
-  ==7593==    at 0x4004FFDF: free (ut_clientmalloc.c:577)
-  ==7593==    by 0x80484C7: main (tests/doublefree.c:10)
-  ==7593==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==7593==    by 0x80483B1: (within tests/doublefree)
+  Invalid free()
+     at 0x4004FFDF: free (ut_clientmalloc.c:577)
+     by 0x80484C7: main (tests/doublefree.c:10)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/doublefree)
+     Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
+     at 0x4004FFDF: free (ut_clientmalloc.c:577)
+     by 0x80484C7: main (tests/doublefree.c:10)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/doublefree)

      Valgrind keeps track of the blocks allocated by your program with malloc/new, so it can know exactly whether or not the argument to @@ -740,7 +790,44 @@ here, the address is one which has previously been freed, you wil be told that -- making duplicate frees of the same block easy to spot. -

      2.6.4  Passing system call parameters with inadequate +

      2.6.4  When a block is freed with an inappropriate +deallocation function

      +For example: +
      +  Mismatched free() / delete / delete []
+     at 0x40303847: DeviceContextImpl::~DeviceContextImpl(void)
+     by 0x45149BCB: nsDeviceContextGTK::~nsDeviceContextGTK(void)
+     by 0x4030341A: DeviceContextImpl::Release(void)
+     by 0x460C0CAC: nsBaseWidget::OnDestroy(void)
+     Address 0x41C11A7C is 0 bytes inside a block of size 120 alloc'd
+     at 0x40040BEC: malloc (vg_clientfuncs.c:100)
+     by 0x4516DAAC: ??? (../../gcc-2.95.3/gcc/cp/new1.cc:78)
+     by 0x4515FA11: nsDeviceContextGTKConstructor(nsISupports *, ...
+     by 0x40553ABB: nsGenericFactory::CreateInstance(nsISupports *, ...
+
      +The following was told to me be the KDE 3 developers. I didn't know +any of it myself. They also implemented the check itself. +

      +In C++ it's important to deallocate memory in a way compatible with +how it was allocated. The deal is: +

        +
      • If allocated with malloc, calloc, + realloc, valloc or + memalign, you must deallocate with free. +
      • If allocated with new [], you must deallocate with + delete []. +
      • If allocated with new, you must deallocate with + delete. +
      +The worst thing is that on Linux apparently it doesn't matter if you +do muddle these up, and it all seems to work ok, but the same program +may then crash on a different platform, Solaris for example. So it's +best to fix it properly. According to the KDE folks "it's amazing how +many C++ programmers don't know this". + + + +

      2.6.5  Passing system call parameters with inadequate read/write permissions

      Valgrind checks all parameters to system calls. If a system call @@ -766,23 +853,23 @@ system call.

      You get this complaint ... 

      -  ==8230== Syscall param write(buf) lacks read permissions
-  ==8230==    at 0x4035E072: __libc_write
-  ==8230==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==8230==    by 0x80483B1: (within tests/badwrite)
-  ==8230==    by <bogus frame pointer> ???
-  ==8230==    Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
-  ==8230==    at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
-  ==8230==    by 0x80484A0: main (tests/badwrite.c:6)
-  ==8230==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==8230==    by 0x80483B1: (within tests/badwrite)
+  Syscall param write(buf) contains uninitialised or unaddressable byte(s)
+     at 0x4035E072: __libc_write
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/badwrite)
+     by <bogus frame pointer> ???
+     Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
+     at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
+     by 0x80484A0: main (tests/badwrite.c:6)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/badwrite)

      ... because the program has tried to write uninitialised junk from the malloc'd block to the standard output. -

      2.6.5  Warning messages you might see

      +

      2.6.6  Warning messages you might see

      Most of these only appear if you run in verbose mode (enabled by -v): @@ -799,11 +886,11 @@ Most of these only appear if you run in verbose mode (enabled by appearance of new errors after the first 50. The 50 constant can be changed by recompiling Valgrind.

      -

    • More than 500 errors detected. I'm not reporting any more. +
    • More than 300 errors detected. I'm not reporting any more. Final error counts may be inaccurate. Go fix your program!
      - After 500 different errors have been detected, Valgrind ignores + 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 @@ -875,7 +962,7 @@ or another, you don't want Valgrind to tell you about. Usually the reason is that the system libraries are buggy but unfixable, at least within the scope of the current debugging session. Multiple suppresions files are allowed. By default, Valgrind uses -linux24.supp in the directory where it is installed. +$PREFIX/lib/valgrind/default.supp.

      You can ask to add suppressions from another file, by specifying @@ -977,28 +1064,13 @@ you can freely mix the obj: and fun: styles of description within a single suppression record. - -

      2.8  Building and installing

      -At the moment, very rudimentary. - -

      The tarball is set up for a standard Red Hat 7.1 (6.2) machine. To -build, just do "make". No configure script, no autoconf, no nothing. - -

      The files needed for installation are: valgrind.so, valgring.so, -valgrind, VERSION, redhat72.supp (or redhat62.supp). You can copy -these to any directory you like. However, you then need to edit the -shell script "valgrind". On line 4, set the environment variable -VALGRIND to point to the directory you have copied the -installation into. - - - -

      2.9  The Client Request mechanism

      + +

      2.8  The Client Request mechanism

      Valgrind has a trapdoor mechanism via which the client program can pass all manner of requests and queries to Valgrind. Internally, this -is used extensively to make malloc, free, signals, etc, work, although -you don't see that. +is used extensively to make malloc, free, signals, threads, etc, work, +although you don't see that.

      For your convenience, a subset of these so-called client requests is provided to allow you to tell Valgrind facts about the behaviour of @@ -1012,6 +1084,8 @@ make this work. The macros therein 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.

      A brief description of the available macros:

        @@ -1070,14 +1144,107 @@ A brief description of the available macros: automatically discards this information when the stack retreats past such blocks. Beware: hacky and flaky, and probably interacts badly with the new pthread support. +

        +

      • RUNNING_ON_VALGRIND: returns 1 if running on + Valgrind, 0 if running on the real CPU. +

        +

      • VALGRIND_DO_LEAK_CHECK: run the memory leak detector + right now. Returns no value. I guess this could be used to + incrementally check for leaks between arbitrary places in the + program's execution. Warning: not properly tested!
      -

      • + +

      2.9  Support for POSIX Pthreads

      + +As of late April 02, Valgrind supports programs which use POSIX +pthreads. Doing this has proved technically challenging and is still +in progress, but it works well enough, as of 1 May 02, for significant +threaded applications to work. +

      +It works as follows: threaded apps are (dynamically) linked against +libpthread.so. Usually this is the one installed with +your Linux distribution. Valgrind, however, supplies its own +libpthread.so and automatically connects your program to +it instead. +

      +The fake libpthread.so 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. +

      +Valgrind schedules your threads in a round-robin fashion, with all +threads having equal priority. It switches threads every 20000 basic +blocks (typically around 120000 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. +

      +The current (1 May 02) state of pthread support is as follows. Please +note that things are advancing rapidly, so the situation may have +improved by the time you read this -- check the web site for further +updates. +

        +
      • Mutexes, condition variables, thread-specific data and + pthread_once currently work. +

        +

      • Various attribute-like calls are handled but ignored. + You get a warning message. +

        +

      • The main big omission is proper cleanup support for cancellation. + pthread_cancel works, but instantly nukes the target + thread without giving it any chance to clean up. Also, when a + thread exits, it does not run any cleanup handlers. +

        +

      • Currently the following syscalls are thread-safe (nonblocking): + write read nanosleep + sleep select and poll. +

        +

      • The POSIX requirement that each thread have its own + signal-blocking mask is not done; the signal handling mechanism is + thread-unaware and all signals are delivered to the main thread, + antidisirregardless. +
      + + +As of 1 May 02, the following 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. +

      +Mozilla 1.0RC1 crashes because it jumps to location zero: Jump +to the invalid address stated on the next line. Other people +have reported the same thing. Despite considerable effort in tracking +this down, I cannot figure out what's going on. If you have a program +which does this, is small enough that I have half a hope of making +sense of it, and is open-source (or at least you'd be happy for me to +look at), I'd be very grateful to have it. +

      +On the other hand, I have received mail from at least one person +who appears to be successful in running CVS builds of Mozilla on +Valgrind. + + + + +

      2.10  Building and installing

      + +We now use the standard Unix ./configure, +make, make install mechanism, and I have +attempted to ensure that it works on machines with kernel 2.2 or 2.4 +and glibc 2.1.X or 2.2.X. I don't think there is much else to say. +There are no options apart from the usual --prefix that +you should give to ./configure. +

      +Let me know if you have build problems. + + -

      2.10  If you have problems

      +

      2.11  If you have problems

      Mail me (jseward@acm.org).

      See Section 4 for the known limitations of @@ -1115,7 +1282,7 @@ which says whether or not the accompanying bit has a legitimate value. In the discussions which follow, this bit is referred to as the V (valid-value) bit. -

      Each byte in the system therefore has a 8 V bits which accompanies +

      Each byte in the system therefore has a 8 V bits which follow it wherever it goes. For example, when the CPU loads a word-size item (4 bytes) from memory, it also loads the corresponding 32 V bits from a bitmap which stores the V bits for the process' entire address @@ -1125,7 +1292,8 @@ stored back in the V-bit bitmap.

      In short, each bit in the system has an associated V bit, which follows it around everywhere, even inside the CPU. Yes, the CPU's -(integer) registers have their own V bit vectors. +(integer and %eflags) registers have their own V bit +vectors.

      Copying values around does not cause Valgrind to check for, or report on, errors. However, when a value is used in a way which might @@ -1166,7 +1334,7 @@ used to generate a memory address, and where control flow decision needs to be made. Also, when a system call is detected, valgrind checks definedness of parameters as required. -

      If a check should detect undefinedness, and error message is +

      If a check should detect undefinedness, an error message is issued. The resulting value is subsequently regarded as well-defined. To do otherwise would give long chains of error messages. In effect, we say that undefined values are non-infectious. @@ -1264,6 +1432,10 @@ themselves do not change the A bits, only consult them. example, mmap() magically makes files appear in the process's address space, so the A bits must be updated if mmap() succeeds.
      +

      + +

    • Optionally, your program can tell Valgrind about such changes + explicitly, using the client request mechanism described above.
    @@ -1450,7 +1622,7 @@ The following list of limitations seems depressingly long. However, most programs actually work fine.

    Valgrind will run x86-GNU/Linux ELF dynamically linked binaries, on -a kernel 2.4.X system, subject to the following constraints: +a kernel 2.2.X or 2.4.X system, subject to the following constraints:

    • No MMX, SSE, SSE2, 3DNow instructions. If the translator @@ -1462,11 +1634,13 @@ a kernel 2.4.X system, subject to the following constraints: the 486 instruction set.

      • -

    • Multithreaded programs are not supported, since I haven't yet - figured out how to do this. To be more specific, it is the - "clone" system call which is not supported. A program calls - "clone" to create threads. Valgrind will abort if this - happens.
      • +
    • 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 libpthread.so, so that Valgrind can + substitute its own implementation at program startup time. If + you're statically linked against it, things will fail + badly.

    • Valgrind assumes that the floating point registers are not used @@ -1491,8 +1665,9 @@ a kernel 2.4.X system, subject to the following constraints: possible.

      • -

    • I have no idea what happens if programs try to handle signals on - an alternate stack (sigaltstack). YMMV.

      • +
    • Programs which try to handle signals on + an alternate stack (sigaltstack) are not supported, although + they could be, with a bit of effort.

    • Programs which switch stacks are not well handled. Valgrind @@ -1501,7 +1676,8 @@ a kernel 2.4.X system, subject to the following constraints: 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.

      • + differently. 1 May 02: this probably interacts badly with the + new pthread support. I haven't checked properly.

    • x86 instructions, and system calls, have been implemented on @@ -1527,50 +1703,30 @@ a kernel 2.4.X system, subject to the following constraints: cause is that Valgrind dynamically translates the original executable and never throws any translation away, except in those rare cases where self-modifying code is detected. - Translated, instrumented code is 8-12 times larger than the + Translated, instrumented code is 12-14 times larger than the original (!) so you can easily end up with 15+ MB of - translations when running (eg) a web browser. There's not a lot - you can do about this -- use Valgrind on a fast machine with a lot - of memory and swap space. At some point I may implement a LRU - caching scheme for translations, so as to bound the maximum - amount of memory devoted to them, to say 8 or 16 MB.
      • + translations when running (eg) a web browser. +
    Programs which are known not to work are:
      -
    • Netscape 4.76 works pretty well on some platforms -- quite - nicely on my AMD K6-III (400 MHz). I can surf, do mail, etc, no - problem. On other platforms is has been observed to crash - during startup. Despite much investigation I can't figure out - why.

      • -

      - -

    • kpackage (a KDE front end to rpm) dies because the CPUID - instruction is unimplemented. Easy to fix.

      • -

      - -

    • knode (a KDE newsreader) tries to do multithreaded things, and - fails.

      • -

      -

    • 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.

      • -

      - -

    • Gimp and Gnome and GTK-based apps die early on because - of unimplemented system call wrappers. (I'm a KDE user :) - This wouldn't be hard to fix. -

      • -

      - -

    • As a consequence of me being a KDE user, almost all KDE apps - work ok -- except those which are multithreaded. -

      • -

      + Valgrind. Emacs works fine if you build it to use the standard + malloc/free routines.
      +

      +

    • Mozilla 1.0RC1 crashes because it jumps to location zero: + Jump to the invalid address stated on the next + line. Other people have reported the same thing. + Despite considerable effort in tracking this down, I cannot + figure out what's going on. If you have a program which does + this, is small enough that I have half a hope of making sense of + it, and is open-source (or at least you'd be happy for me to + look at), I'd be very grateful to have it.
    diff --git a/docs/nav.html b/docs/nav.html index 686ac2bde8..ad920ad443 100644 --- a/docs/nav.html +++ b/docs/nav.html @@ -41,8 +41,10 @@ 2.5 Command-line flags
    2.6 Explanation of error messages
    2.7 Writing suppressions files
    - 2.8 Building and installing
    - 2.9 If you have problems + 2.8 The Client Request mechanism
    + 2.9 Support for POSIX pthreads
    + 2.10 Building and installing
    + 2.11 If you have problems

    3 Details of the checking machinery
    3.1 Valid-value (V) bits
    @@ -62,7 +64,9 @@

    6 An example

    - 7 The design and implementation of Valgrind
    + 7 Cache profiling +

    + 8 The design and implementation of Valgrind
    diff --git a/memcheck/docs/manual.html b/memcheck/docs/manual.html index daaa1535d1..db1d28326f 100644 --- a/memcheck/docs/manual.html +++ b/memcheck/docs/manual.html @@ -24,8 +24,8 @@   -

    Valgrind, snapshot 20020324

    -
    This manual was minimally updated on 20020415
    +

    Valgrind, snapshot 20020501

    +
    This manual was majorly updated on 20020501

    @@ -57,8 +57,10 @@ Linux-x86 executables. 2.5  Command-line flags
    2.6  Explaination of error messages
    2.7  Writing suppressions files
    - 2.8  Building and installing
    - 2.9  If you have problems
    + 2.8  The Client Request mechanism
    + 2.9  Support for POSIX pthreads
    + 2.10  Building and installing
    + 2.11  If you have problems

    3  Details of the checking machinery

    3.1  Valid-value (V) bits
    @@ -112,18 +114,12 @@ 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 I have chosen at the outset to concentrate on what I believe to be a widely used platform: Red Hat -Linux 7.2, on x86s. I believe that it will work without significant -difficulty on other x86 GNU/Linux systems which use the 2.4 kernel and -GNU libc 2.2.X, for example SuSE 7.1 and Mandrake 8.0. Red Hat 6.2 is -also supported. It has worked in the past, and probably still does, -on RedHat 7.1 and 6.2. Note that I haven't compiled it on RedHat 7.1 -and 6.2 for a while, so they may no longer work now. -

    -(Early Feb 02: after feedback from the KDE people it also works better -on other Linuxes). -

    -At some point in the past, Valgrind has also worked on Red Hat 6.2 -(x86), thanks to the efforts of Rob Noble. +Linux 7.2, on x86s. Valgrind uses the standard Unix +./configure, make, make install +mechanism, and I have attempted to ensure that it works on machines +with kernel 2.2 or 2.4 and glibc 2.1.X or 2.2.X. This should cover +the vast majority of modern Linux installations. +

    Valgrind is licensed under the GNU General Public License, version @@ -148,26 +144,27 @@ checks every memory access. All detected errors are written to a log. When the program finishes, Valgrind searches for and reports on leaked memory. -

    You can run pretty much any dynamically linked ELF x86 executable using -Valgrind. Programs run 25 to 50 times slower, and take a lot more -memory, than they usually would. It works well enough to run large -programs. For example, the Konqueror web browser from the KDE Desktop -Environment, version 2.1.1, runs slowly but usably on Valgrind. +

    You can run pretty much any dynamically linked ELF x86 executable +using Valgrind. Programs run 25 to 50 times slower, and take a lot +more memory, than they usually would. It works well enough to run +large programs. For example, the Konqueror web browser from the KDE +Desktop Environment, version 3.0, runs slowly but usably on Valgrind.

    Valgrind simulates every single instruction your program executes. Because of this, it finds errors not only in your application but also -in all supporting dynamically-linked (.so-format) libraries, including -the GNU C library, the X client libraries, Qt, if you work with KDE, and -so on. That often includes libraries, for example the GNU C library, -which contain memory access violations, but which you cannot or do not -want to fix. +in all supporting dynamically-linked (.so-format) +libraries, including the GNU C library, the X client libraries, Qt, if +you work with KDE, and so on. That often includes libraries, for +example the GNU C library, which contain memory access violations, but +which you cannot or do not want to fix.

    Rather than swamping you with errors in which you are not interested, Valgrind allows you to selectively suppress errors, by recording them in a suppressions file which is read when Valgrind -starts up. As supplied, Valgrind comes with a suppressions file -designed to give reasonable behaviour on Red Hat 7.2 (also 7.1 and -6.2) when running text-only and simple X applications. +starts up. The build mechanism attempts to select suppressions which +give reasonable behaviour for the libc and XFree86 versions detected +on your machine. +

    Section 6 shows an example of use.

    @@ -185,9 +182,25 @@ debugging info enabled (the -g flag). 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. +debugger. -

    Then just run your application, but place the word +

    +A plausible compromise is to use -g -O. +Optimisation levels above -O have been observed, on very +rare occasions, to cause gcc to generate code which fools Valgrind's +error tracking machinery into wrongly reporting uninitialised value +errors. -O gets you the vast majority of the benefits of +higher optimisation levels anyway, so you don't lose much there. + +

    +Note that as of 1 May 2002 Valgrind does not understand the DWARF +debugging format, which is unfortunate since the upcoming gcc-3.1 uses +it by default. Valgrind only knows about the older "stabs" format. +If you use gcc-3.1 or above, you can still ask for stabs-format debug +info by passing -gstabs to gcc. + +

    +Then just run your application, but place the word valgrind in front of your usual command-line invokation. Note that you should run the real (machine-code) executable here. If your application is started by, for example, a shell or perl script, @@ -195,7 +208,7 @@ 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 /bin/sh, /usr/bin/perl, or whatever interpreter you're using. -This almost certainly isn't what you want and can be hugely confusing. +This almost certainly isn't what you want and can be confusing.

    2.2  The commentary

    @@ -265,6 +278,17 @@ later uses them, will generate several error messages. The first such error message may well give the most direct clue to the root cause of the problem. +

    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 vg_include.h and can be increased +if necessary. +

    2.4  Suppressing errors

    @@ -272,14 +296,15 @@ Valgrind detects 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. By default -this file is redhat72.supp, located in the Valgrind -installation directory. +Valgrind reads a list of errors to suppress at startup. +A default suppression file is cooked up by the +./configure script. -

    You can modify and add to the suppressions file at your leisure, or -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. +

    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.

    Each error to be suppressed is described very specifically, to minimise the possibility that a suppression-directive inadvertantly @@ -305,6 +330,10 @@ You invoke Valgrind like this: valgrind [options-for-Valgrind] your-prog [options for your-prog] +

    Note that Valgrind also reads options from the environment variable +$VALGRIND, and processes them before the command-line +options. +

    Valgrind's default settings succeed in giving reasonable behaviour in most cases. Available options, in no particular order, are as follows: @@ -380,10 +409,12 @@ follows: or c Ret causes Valgrind not to start GDB, and not to ask again.

    - --gdb-attach=yes conflicts with - --trace-children=yes. You can't use them - together. Valgrind refuses to start up in this situation. -

    + --gdb-attach=yes conflicts with + --trace-children=yes. You can't use them together. + Valgrind refuses to start up in this situation. 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.

  • --partial-loads-ok=yes [the default]
    --partial-loads-ok=no @@ -411,16 +442,25 @@ follows: 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. Valgrind snapshots dated 17 Feb 2002 and later are + these areas. +

    + Valgrind snapshots dated 17 Feb 2002 and later are cleverer about this problem, and you should no longer need to - use this flag. + use this flag. To put it bluntly, if you do need to use this + flag, your program violates the ANSI C semantics defined for + malloc and free, even if it appears to + work correctly, and you should fix it, at least if you hope for + maximum portability.


  • --trace-children=no [the default]
    --trace-children=yes

    When enabled, Valgrind will trace into child processes. This is confusing and usually not what you want, so is disabled by - default.


    • + default. As of 1 May 2002, tracing into a child process from a + parent which uses libpthread.so is probably broken + and is likely to cause breakage. Please report any such + problems to me.

  • --freelist-vol=<number> [default: 1000000]

    When the client program releases memory using free (in C) or @@ -451,41 +491,41 @@ follows: and ask the shell to route file descriptor 9 to "logfile".


    • -

  • --suppressions=<filename> [default: - /installation/directory/redhat72.supp]

    Specifies an extra +

  • --suppressions=<filename> + [default: $PREFIX/lib/valgrind/default.supp] +

    Specifies an extra file from which to read descriptions of errors to suppress. You may use as many extra suppressions files as you like.


  • --leak-check=no [default]
    - --leak-check=yes + --leak-check=yes

    When enabled, search for memory leaks when the client program finishes. A memory leak means a malloc'd block, which has not yet been free'd, but to which no pointer can be found. Such a block can never be free'd by the program, since no pointer to it - exists. Leak checking is disabled by default - because it tends to generate dozens of error messages. -


    • + exists. Leak checking is disabled by default because it tends + to generate dozens of error messages.

  • --show-reachable=no [default]
    - --show-reachable=yes

    When disabled, the memory - leak detector only shows blocks for which it cannot find a - pointer to at all, or it can only find a pointer to the middle - of. These blocks are prime candidates for memory leaks. When - enabled, the leak detector also reports on blocks which it could - find a pointer to. Your program could, at least in principle, - have freed such blocks before exit. Contrast this to blocks for - which no pointer, or only an interior pointer could be found: - they are more likely to indicate memory leaks, because - you do not actually have a pointer to the start of the block - which you can hand to free(), even if you wanted to. -


    • + --show-reachable=yes +

    When disabled, the memory leak detector only shows blocks for + which it cannot find a pointer to at all, or it can only find a + pointer to the middle of. These blocks are prime candidates for + memory leaks. When enabled, the leak detector also reports on + blocks which it could find a pointer to. Your program could, at + least in principle, have freed such blocks before exit. + Contrast this to blocks for which no pointer, or only an + interior pointer could be found: they are more likely to + indicate memory leaks, because you do not actually have a + pointer to the start of the block which you can hand to + free, even if you wanted to.

  • --leak-resolution=low [default]
    --leak-resolution=med
    --leak-resolution=high

    When doing leak checking, determines how willing Valgrind is - to consider different backtraces the same. When set to + to consider different backtraces to be the same. When set to low, the default, only the first two entries need match. When med, four entries have to match. When high, all entries need to match. @@ -499,7 +539,7 @@ follows:

    Note that the --leak-resolution= setting does not affect Valgrind's ability to find leaks. It only changes how - the results are presented to you. + the results are presented.


  • --workaround-gcc296-bugs=no [default]
    @@ -514,7 +554,9 @@ follows: gcc/g++ which works properly; 2.95.3 seems to be a good choice.

    Unfortunately (27 Feb 02) it looks like g++ 3.0.4 is similarly - buggy, so you may need to issue this flag if you use 3.0.4. + buggy, so you may need to issue this flag if you use 3.0.4. A + while later (early Apr 02) this is confirmed as a scheduling bug + in g++-3.0.4.


  • --cachesim=no [default]
    @@ -595,13 +637,13 @@ shouldn't need to use them in the normal run of things. Nevertheless:

    • -

  • --dump-error=<number> - [default: inactive] +
  • --dump-error=<number> [default: inactive]

    After the program has exited, show gory details of the translation of the basic block containing the <number>'th - error context. When used with --single-step=yes, - can show the - exact x86 instruction causing an error.


    • + error context. When used with --single-step=yes, + can show the exact x86 instruction causing an error. This is + all fairly dodgy and doesn't work at all if threads are + involved.

  • --smc-check=none
    @@ -613,7 +655,15 @@ shouldn't need to use them in the normal run of things. Nevertheless: resulting from moves from integer registers to memory are checked. When "all", all memory writes are checked, even those with which are no sane program would generate code -- for - example, floating-point writes.
    • + example, floating-point writes. +

    + NOTE that this is all a bit bogus. This mechanism has never + been enabled in any snapshot of Valgrind which was made + available to the general public, because the extra checks reduce + performance, increase complexity, and I have yet to come across + any programs which actually use self-modifying code. I think + the flag is ignored. + @@ -632,12 +682,12 @@ precise behaviour of the error-checking machinery is described in

    2.6.1  Illegal read / Illegal write errors

    For example: 
    -  ==30975== Invalid read of size 4
-  ==30975==    at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
-  ==30975==    by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
-  ==30975==    by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
-  ==30975==    Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
+  Invalid read of size 4
+     at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
+     by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
+     by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
+     Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd

    This happens when your program reads or writes memory at a place @@ -658,7 +708,8 @@ fact, and also where the block was malloc'd.

    In this example, Valgrind can't identify the address. Actually the address is on the stack, but, for some reason, this is not a valid stack address -- it is below the stack pointer, %esp, and that isn't -allowed. +allowed. In this particular case it's probably caused by gcc +generating invalid code, a known bug in various flavours of gcc.

    Note that Valgrind only tells you that your program is about to access memory at an illegal address. It can't stop the access from @@ -672,11 +723,11 @@ non-fatal, and the program stays alive.

    2.6.2  Use of uninitialised values

    For example: 
    -  ==19146== Conditional jump or move depends on uninitialised value(s)
-  ==19146==    at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
-  ==19146==    by 0x402E8476: _IO_printf (printf.c:36)
-  ==19146==    by 0x8048472: main (tests/manuel1.c:8)
-  ==19146==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+  Conditional jump or move depends on uninitialised value(s)
+     at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
+     by 0x402E8476: _IO_printf (printf.c:36)
+     by 0x8048472: main (tests/manuel1.c:8)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)

    An uninitialised-value use error is reported when your program uses @@ -697,11 +748,10 @@ junk (uninitialised) data to its heart's content. Valgrind observes this and keeps track of the data, but does not complain. A complaint is issued only when your program attempts to make use of uninitialised data. In this example, x is uninitialised. Valgrind observes the -value being passed to _IO_printf and thence to -_IO_vfprintf, but makes no comment. However, -_IO_vfprintf has to examine the value of x -so it can turn it into the corresponding ASCII string, and it is at -this point that Valgrind complains. +value being passed to _IO_printf and thence to _IO_vfprintf, but makes +no comment. However, _IO_vfprintf has to examine the value of x so it +can turn it into the corresponding ASCII string, and it is at this +point that Valgrind complains.

    Sources of uninitialised data tend to be:

      @@ -720,16 +770,16 @@ this point that Valgrind complains.

      2.6.3  Illegal frees

      For example: 
      -  ==7593== Invalid free()
-  ==7593==    at 0x4004FFDF: free (ut_clientmalloc.c:577)
-  ==7593==    by 0x80484C7: main (tests/doublefree.c:10)
-  ==7593==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==7593==    by 0x80483B1: (within tests/doublefree)
-  ==7593==    Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
-  ==7593==    at 0x4004FFDF: free (ut_clientmalloc.c:577)
-  ==7593==    by 0x80484C7: main (tests/doublefree.c:10)
-  ==7593==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==7593==    by 0x80483B1: (within tests/doublefree)
+  Invalid free()
+     at 0x4004FFDF: free (ut_clientmalloc.c:577)
+     by 0x80484C7: main (tests/doublefree.c:10)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/doublefree)
+     Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
+     at 0x4004FFDF: free (ut_clientmalloc.c:577)
+     by 0x80484C7: main (tests/doublefree.c:10)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/doublefree)

      Valgrind keeps track of the blocks allocated by your program with malloc/new, so it can know exactly whether or not the argument to @@ -740,7 +790,44 @@ here, the address is one which has previously been freed, you wil be told that -- making duplicate frees of the same block easy to spot. -

      2.6.4  Passing system call parameters with inadequate +

      2.6.4  When a block is freed with an inappropriate +deallocation function

      +For example: +
      +  Mismatched free() / delete / delete []
+     at 0x40303847: DeviceContextImpl::~DeviceContextImpl(void)
+     by 0x45149BCB: nsDeviceContextGTK::~nsDeviceContextGTK(void)
+     by 0x4030341A: DeviceContextImpl::Release(void)
+     by 0x460C0CAC: nsBaseWidget::OnDestroy(void)
+     Address 0x41C11A7C is 0 bytes inside a block of size 120 alloc'd
+     at 0x40040BEC: malloc (vg_clientfuncs.c:100)
+     by 0x4516DAAC: ??? (../../gcc-2.95.3/gcc/cp/new1.cc:78)
+     by 0x4515FA11: nsDeviceContextGTKConstructor(nsISupports *, ...
+     by 0x40553ABB: nsGenericFactory::CreateInstance(nsISupports *, ...
+
      +The following was told to me be the KDE 3 developers. I didn't know +any of it myself. They also implemented the check itself. +

      +In C++ it's important to deallocate memory in a way compatible with +how it was allocated. The deal is: +

        +
      • If allocated with malloc, calloc, + realloc, valloc or + memalign, you must deallocate with free. +
      • If allocated with new [], you must deallocate with + delete []. +
      • If allocated with new, you must deallocate with + delete. +
      +The worst thing is that on Linux apparently it doesn't matter if you +do muddle these up, and it all seems to work ok, but the same program +may then crash on a different platform, Solaris for example. So it's +best to fix it properly. According to the KDE folks "it's amazing how +many C++ programmers don't know this". + + + +

      2.6.5  Passing system call parameters with inadequate read/write permissions

      Valgrind checks all parameters to system calls. If a system call @@ -766,23 +853,23 @@ system call.

      You get this complaint ... 

      -  ==8230== Syscall param write(buf) lacks read permissions
-  ==8230==    at 0x4035E072: __libc_write
-  ==8230==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==8230==    by 0x80483B1: (within tests/badwrite)
-  ==8230==    by <bogus frame pointer> ???
-  ==8230==    Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
-  ==8230==    at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
-  ==8230==    by 0x80484A0: main (tests/badwrite.c:6)
-  ==8230==    by 0x402A6E5E: __libc_start_main (libc-start.c:129)
-  ==8230==    by 0x80483B1: (within tests/badwrite)
+  Syscall param write(buf) contains uninitialised or unaddressable byte(s)
+     at 0x4035E072: __libc_write
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/badwrite)
+     by <bogus frame pointer> ???
+     Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
+     at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
+     by 0x80484A0: main (tests/badwrite.c:6)
+     by 0x402A6E5E: __libc_start_main (libc-start.c:129)
+     by 0x80483B1: (within tests/badwrite)

      ... because the program has tried to write uninitialised junk from the malloc'd block to the standard output. -

      2.6.5  Warning messages you might see

      +

      2.6.6  Warning messages you might see

      Most of these only appear if you run in verbose mode (enabled by -v): @@ -799,11 +886,11 @@ Most of these only appear if you run in verbose mode (enabled by appearance of new errors after the first 50. The 50 constant can be changed by recompiling Valgrind.

      -

    • More than 500 errors detected. I'm not reporting any more. +
    • More than 300 errors detected. I'm not reporting any more. Final error counts may be inaccurate. Go fix your program!
      - After 500 different errors have been detected, Valgrind ignores + 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 @@ -875,7 +962,7 @@ or another, you don't want Valgrind to tell you about. Usually the reason is that the system libraries are buggy but unfixable, at least within the scope of the current debugging session. Multiple suppresions files are allowed. By default, Valgrind uses -linux24.supp in the directory where it is installed. +$PREFIX/lib/valgrind/default.supp.

      You can ask to add suppressions from another file, by specifying @@ -977,28 +1064,13 @@ you can freely mix the obj: and fun: styles of description within a single suppression record. - -

      2.8  Building and installing

      -At the moment, very rudimentary. - -

      The tarball is set up for a standard Red Hat 7.1 (6.2) machine. To -build, just do "make". No configure script, no autoconf, no nothing. - -

      The files needed for installation are: valgrind.so, valgring.so, -valgrind, VERSION, redhat72.supp (or redhat62.supp). You can copy -these to any directory you like. However, you then need to edit the -shell script "valgrind". On line 4, set the environment variable -VALGRIND to point to the directory you have copied the -installation into. - - - -

      2.9  The Client Request mechanism

      + +

      2.8  The Client Request mechanism

      Valgrind has a trapdoor mechanism via which the client program can pass all manner of requests and queries to Valgrind. Internally, this -is used extensively to make malloc, free, signals, etc, work, although -you don't see that. +is used extensively to make malloc, free, signals, threads, etc, work, +although you don't see that.

      For your convenience, a subset of these so-called client requests is provided to allow you to tell Valgrind facts about the behaviour of @@ -1012,6 +1084,8 @@ make this work. The macros therein 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.

      A brief description of the available macros:

        @@ -1070,14 +1144,107 @@ A brief description of the available macros: automatically discards this information when the stack retreats past such blocks. Beware: hacky and flaky, and probably interacts badly with the new pthread support. +

        +

      • RUNNING_ON_VALGRIND: returns 1 if running on + Valgrind, 0 if running on the real CPU. +

        +

      • VALGRIND_DO_LEAK_CHECK: run the memory leak detector + right now. Returns no value. I guess this could be used to + incrementally check for leaks between arbitrary places in the + program's execution. Warning: not properly tested!
      -

      • + +

      2.9  Support for POSIX Pthreads

      + +As of late April 02, Valgrind supports programs which use POSIX +pthreads. Doing this has proved technically challenging and is still +in progress, but it works well enough, as of 1 May 02, for significant +threaded applications to work. +

      +It works as follows: threaded apps are (dynamically) linked against +libpthread.so. Usually this is the one installed with +your Linux distribution. Valgrind, however, supplies its own +libpthread.so and automatically connects your program to +it instead. +

      +The fake libpthread.so 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. +

      +Valgrind schedules your threads in a round-robin fashion, with all +threads having equal priority. It switches threads every 20000 basic +blocks (typically around 120000 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. +

      +The current (1 May 02) state of pthread support is as follows. Please +note that things are advancing rapidly, so the situation may have +improved by the time you read this -- check the web site for further +updates. +

        +
      • Mutexes, condition variables, thread-specific data and + pthread_once currently work. +

        +

      • Various attribute-like calls are handled but ignored. + You get a warning message. +

        +

      • The main big omission is proper cleanup support for cancellation. + pthread_cancel works, but instantly nukes the target + thread without giving it any chance to clean up. Also, when a + thread exits, it does not run any cleanup handlers. +

        +

      • Currently the following syscalls are thread-safe (nonblocking): + write read nanosleep + sleep select and poll. +

        +

      • The POSIX requirement that each thread have its own + signal-blocking mask is not done; the signal handling mechanism is + thread-unaware and all signals are delivered to the main thread, + antidisirregardless. +
      + + +As of 1 May 02, the following 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. +

      +Mozilla 1.0RC1 crashes because it jumps to location zero: Jump +to the invalid address stated on the next line. Other people +have reported the same thing. Despite considerable effort in tracking +this down, I cannot figure out what's going on. If you have a program +which does this, is small enough that I have half a hope of making +sense of it, and is open-source (or at least you'd be happy for me to +look at), I'd be very grateful to have it. +

      +On the other hand, I have received mail from at least one person +who appears to be successful in running CVS builds of Mozilla on +Valgrind. + + + + +

      2.10  Building and installing

      + +We now use the standard Unix ./configure, +make, make install mechanism, and I have +attempted to ensure that it works on machines with kernel 2.2 or 2.4 +and glibc 2.1.X or 2.2.X. I don't think there is much else to say. +There are no options apart from the usual --prefix that +you should give to ./configure. +

      +Let me know if you have build problems. + + -

      2.10  If you have problems

      +

      2.11  If you have problems

      Mail me (jseward@acm.org).

      See Section 4 for the known limitations of @@ -1115,7 +1282,7 @@ which says whether or not the accompanying bit has a legitimate value. In the discussions which follow, this bit is referred to as the V (valid-value) bit. -

      Each byte in the system therefore has a 8 V bits which accompanies +

      Each byte in the system therefore has a 8 V bits which follow it wherever it goes. For example, when the CPU loads a word-size item (4 bytes) from memory, it also loads the corresponding 32 V bits from a bitmap which stores the V bits for the process' entire address @@ -1125,7 +1292,8 @@ stored back in the V-bit bitmap.

      In short, each bit in the system has an associated V bit, which follows it around everywhere, even inside the CPU. Yes, the CPU's -(integer) registers have their own V bit vectors. +(integer and %eflags) registers have their own V bit +vectors.

      Copying values around does not cause Valgrind to check for, or report on, errors. However, when a value is used in a way which might @@ -1166,7 +1334,7 @@ used to generate a memory address, and where control flow decision needs to be made. Also, when a system call is detected, valgrind checks definedness of parameters as required. -

      If a check should detect undefinedness, and error message is +

      If a check should detect undefinedness, an error message is issued. The resulting value is subsequently regarded as well-defined. To do otherwise would give long chains of error messages. In effect, we say that undefined values are non-infectious. @@ -1264,6 +1432,10 @@ themselves do not change the A bits, only consult them. example, mmap() magically makes files appear in the process's address space, so the A bits must be updated if mmap() succeeds.
      +

      + +

    • Optionally, your program can tell Valgrind about such changes + explicitly, using the client request mechanism described above.
    @@ -1450,7 +1622,7 @@ The following list of limitations seems depressingly long. However, most programs actually work fine.

    Valgrind will run x86-GNU/Linux ELF dynamically linked binaries, on -a kernel 2.4.X system, subject to the following constraints: +a kernel 2.2.X or 2.4.X system, subject to the following constraints:

    • No MMX, SSE, SSE2, 3DNow instructions. If the translator @@ -1462,11 +1634,13 @@ a kernel 2.4.X system, subject to the following constraints: the 486 instruction set.

      • -

    • Multithreaded programs are not supported, since I haven't yet - figured out how to do this. To be more specific, it is the - "clone" system call which is not supported. A program calls - "clone" to create threads. Valgrind will abort if this - happens.
      • +
    • 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 libpthread.so, so that Valgrind can + substitute its own implementation at program startup time. If + you're statically linked against it, things will fail + badly.

    • Valgrind assumes that the floating point registers are not used @@ -1491,8 +1665,9 @@ a kernel 2.4.X system, subject to the following constraints: possible.

      • -

    • I have no idea what happens if programs try to handle signals on - an alternate stack (sigaltstack). YMMV.

      • +
    • Programs which try to handle signals on + an alternate stack (sigaltstack) are not supported, although + they could be, with a bit of effort.

    • Programs which switch stacks are not well handled. Valgrind @@ -1501,7 +1676,8 @@ a kernel 2.4.X system, subject to the following constraints: 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.

      • + differently. 1 May 02: this probably interacts badly with the + new pthread support. I haven't checked properly.

    • x86 instructions, and system calls, have been implemented on @@ -1527,50 +1703,30 @@ a kernel 2.4.X system, subject to the following constraints: cause is that Valgrind dynamically translates the original executable and never throws any translation away, except in those rare cases where self-modifying code is detected. - Translated, instrumented code is 8-12 times larger than the + Translated, instrumented code is 12-14 times larger than the original (!) so you can easily end up with 15+ MB of - translations when running (eg) a web browser. There's not a lot - you can do about this -- use Valgrind on a fast machine with a lot - of memory and swap space. At some point I may implement a LRU - caching scheme for translations, so as to bound the maximum - amount of memory devoted to them, to say 8 or 16 MB.
      • + translations when running (eg) a web browser. +
    Programs which are known not to work are:
      -
    • Netscape 4.76 works pretty well on some platforms -- quite - nicely on my AMD K6-III (400 MHz). I can surf, do mail, etc, no - problem. On other platforms is has been observed to crash - during startup. Despite much investigation I can't figure out - why.

      • -

      - -

    • kpackage (a KDE front end to rpm) dies because the CPUID - instruction is unimplemented. Easy to fix.

      • -

      - -

    • knode (a KDE newsreader) tries to do multithreaded things, and - fails.

      • -

      -

    • 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.

      • -

      - -

    • Gimp and Gnome and GTK-based apps die early on because - of unimplemented system call wrappers. (I'm a KDE user :) - This wouldn't be hard to fix. -

      • -

      - -

    • As a consequence of me being a KDE user, almost all KDE apps - work ok -- except those which are multithreaded. -

      • -

      + Valgrind. Emacs works fine if you build it to use the standard + malloc/free routines.
      +

      +

    • Mozilla 1.0RC1 crashes because it jumps to location zero: + Jump to the invalid address stated on the next + line. Other people have reported the same thing. + Despite considerable effort in tracking this down, I cannot + figure out what's going on. If you have a program which does + this, is small enough that I have half a hope of making sense of + it, and is open-source (or at least you'd be happy for me to + look at), I'd be very grateful to have it.
    diff --git a/memcheck/docs/nav.html b/memcheck/docs/nav.html index 686ac2bde8..ad920ad443 100644 --- a/memcheck/docs/nav.html +++ b/memcheck/docs/nav.html @@ -41,8 +41,10 @@ 2.5 Command-line flags
    2.6 Explanation of error messages
    2.7 Writing suppressions files
    - 2.8 Building and installing
    - 2.9 If you have problems + 2.8 The Client Request mechanism
    + 2.9 Support for POSIX pthreads
    + 2.10 Building and installing
    + 2.11 If you have problems

    3 Details of the checking machinery
    3.1 Valid-value (V) bits
    @@ -62,7 +64,9 @@

    6 An example

    - 7 The design and implementation of Valgrind
    + 7 Cache profiling +

    + 8 The design and implementation of Valgrind