From: Julian Seward Date: Sun, 4 May 2008 23:06:28 +0000 (+0000) Subject: Add documentation on the new --track-origins=no|yes [no] flag. X-Git-Tag: svn/VALGRIND_3_4_0~631 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=edb789f73abafa20f3e32417801168f98a952724;p=thirdparty%2Fvalgrind.git Add documentation on the new --track-origins=no|yes [no] flag. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@8006 --- diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index 95707b5ac5..27ee1bcfd4 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -60,6 +60,78 @@ the following problems: + + + + + + Controls whether memcheck reports + uses of undefined value errors. Set this to + no if you don't want to see undefined value + errors. It also has the side effect of speeding up + memcheck somewhat. + + + + + + + + + + Controls whether memcheck tracks + the origin of uninitialised values. By default, it does not, + which means that although it can tell you that an + uninitialised value is being used in a dangerous way, it + cannot tell you where the uninitialised value came from. This + often makes it difficult to track down the root problem. + + When set + to yes, memcheck keeps + track of the origins of all uninitialised values. Then, when + an uninitialised value error is + reported, memcheck will try to show the + origin of the value. An origin can be one of the following + four places: a heap block, a stack allocation, a client + request, or miscellaneous other sources (eg, a call + to brk). + + For uninitialised values originating from a heap + block, memcheck shows where the block was + allocated. For uninitialised values originating from a stack + allocation, memcheck can tell you which + function allocated the value, but no more than that -- typically + it shows you the source location of the opening brace of the + function. So you should carefully check that all of the + function's local variables are initialised properly. + + Performance overhead: origin tracking is expensive. It + halves memcheck's speed and increases + memory use by a minimum of 100MB, and possibly more. + Nevertheless it can drastically reduce the effort required to + identify the root cause of uninitialised value errors, and so + is often a programmer productivity win, despite running + more slowly. + + Accuracy: memcheck tracks origins + quite accurately. To avoid very large space and time + overheads, some approximations are made. It is possible, + although unlikely, that + memcheck will report an incorrect origin, + or not be able to identify any origin. + + Note that the combination + + and is + nonsensical. memcheck checks for and + rejects this combination at startup. + + Origin tracking is a new feature, introduced in Valgrind + version 3.4.0. + + + + @@ -193,20 +265,6 @@ the following problems: - - - - - - Controls whether memcheck detects - dangerous uses of undefined value errors. Set this to - no if you don't like seeing undefined value - errors; it also has the side effect of speeding - memcheck up somewhat. - - - - @@ -356,6 +414,11 @@ complains. +To see information on the sources of uninitialised data in your +program, use the flag. This +makes Memcheck run more slowly, but can make it much easier to track down +the root causes of uninitialised value errors. +