diff --git a/coregrind/docs/coregrind_core.html b/coregrind/docs/coregrind_core.html index edf4d49a9..e1cbc06a2 100644 --- a/coregrind/docs/coregrind_core.html +++ b/coregrind/docs/coregrind_core.html @@ -327,6 +327,11 @@ 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. +

+Note: By far the easiest way to add suppressions is to use the +--gen-suppressions=yes flag described in this +section. +

Each error to be suppressed is described very specifically, to minimise the possibility that a suppression-directive inadvertantly @@ -345,6 +350,122 @@ number of times it got used. Here's the suppressions used by a run of --27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object +

+Multiple suppressions files are allowed. By default, Valgrind uses +$PREFIX/lib/valgrind/default.supp. You can ask to add +suppressions from another file, by specifying +--suppressions=/path/to/file.supp. + +

+If you want to understand more about suppressions, look at an existing +suppressions file whilst reading the following documentation. The file +glibc-2.2.supp, in the source distribution, provides some good +examples. + +

Each suppression has the following components:
+

+ +

+ +A suppression only suppresses an error when the error matches all the +details in the suppression. Here's an example: +

+  {
+    __gconv_transform_ascii_internal/__mbrtowc/mbtowc
+    Memcheck:Value4
+    fun:__gconv_transform_ascii_internal
+    fun:__mbr*toc
+    fun:mbtowc
+  }
+
+ +

What is means is: in the Memcheck skin only, suppress a +use-of-uninitialised-value error, when the data size is 4, when it +occurs in the function __gconv_transform_ascii_internal, +when that is called from any function of name matching +__mbr*toc, when that is called from mbtowc. +It doesn't apply under any other circumstances. The string by which +this suppression is identified to the user is +__gconv_transform_ascii_internal/__mbrtowc/mbtowc. +

+(See this section for more details on +the specifics of Memcheck's suppression kinds.) + +

Another example, again for the Memcheck skin: +

+  {
+    libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
+    Memcheck:Value4
+    obj:/usr/X11R6/lib/libX11.so.6.2
+    obj:/usr/X11R6/lib/libX11.so.6.2
+    obj:/usr/X11R6/lib/libXaw.so.7.0
+  }
+
+ +

Suppress any size 4 uninitialised-value error which occurs anywhere +in libX11.so.6.2, when called from anywhere in the same +library, when called from anywhere in libXaw.so.7.0. The +inexact specification of locations is regrettable, but is about all +you can hope for, given that the X11 libraries shipped with Red Hat +7.2 have had their symbol tables removed. + +

Note -- since the above two examples did not make it clear -- that +you can freely mix the obj: and fun: +styles of description within a single suppression record. +

2.6  Command-line flags for the Valgrind core

diff --git a/memcheck/docs/mc_main.html b/memcheck/docs/mc_main.html index 66f14052a..5330650a9 100644 --- a/memcheck/docs/mc_main.html +++ b/memcheck/docs/mc_main.html @@ -375,158 +375,57 @@ partially trashed by the copying.

3.4  Writing suppressions files

+The basic suppression format was described in this section.

-A suppression file describes a bunch of errors which, for one reason -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 -suppressions files are allowed. By default, Valgrind uses -$PREFIX/lib/valgrind/default.supp. - -

-You can ask to add suppressions from another file, by specifying ---suppressions=/path/to/file.supp. - -

-A good way to get started writing your own suppressions is to -look at an existing suppressions file whilst reading the following -documentation. The file glibc-2.2.supp, in the source -distribution, provides some good examples. - -

Each suppression has the following components:
-

- -

-Locations may be either names of shared objects/executables or wildcards -matching function names. They begin obj: and fun: -respectively. Function and object names to match against may use the -wildcard characters * and ?. - -A suppression only suppresses an error when the error matches all the -details in the suppression. Here's an example: +The suppression (2nd) line should have the form: 

-  {
-    __gconv_transform_ascii_internal/__mbrtowc/mbtowc
-    Memcheck:Value4
-    fun:__gconv_transform_ascii_internal
-    fun:__mbr*toc
-    fun:mbtowc
-  }
+Memcheck:suppression_type
+
+Or, since some of the suppressions are shared with the Addrcheck skin: +
+Memcheck,Addrcheck:suppression_type
-

What is means is: in the Memcheck skin only, suppress a -use-of-uninitialised-value error, when the data size is 4, when it -occurs in the function __gconv_transform_ascii_internal, -when that is called from any function of name matching -__mbr*toc, when that is called from mbtowc. -It doesn't apply under any other circumstances. The string by which -this suppression is identified to the user is -__gconv_transform_ascii_internal/__mbrtowc/mbtowc. - -

Another example, again for the Memcheck skin: -

-  {
-    libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
-    Memcheck:Value4
-    obj:/usr/X11R6/lib/libX11.so.6.2
-    obj:/usr/X11R6/lib/libX11.so.6.2
-    obj:/usr/X11R6/lib/libXaw.so.7.0
-  }
-
- -

Suppress any size 4 uninitialised-value error which occurs anywhere -in libX11.so.6.2, when called from anywhere in the same -library, when called from anywhere in libXaw.so.7.0. The -inexact specification of locations is regrettable, but is about all -you can hope for, given that the X11 libraries shipped with Red Hat -7.2 have had their symbol tables removed. - -

Note -- since the above two examples did not make it clear -- that -you can freely mix the obj: and fun: -styles of description within a single suppression record. - - - +

+The Memcheck suppression types are as follows: +Value1, +Value2, +Value4 or +Value8, +meaning an uninitialised-value error when +using a value of 1, 2, 4 or 8 bytes. +Or +Cond (or its old name, Value0), +meaning use of an uninitialised CPU condition code. Or: +Addr1, +Addr2, +Addr4 or +Addr8, meaning an invalid address during a +memory access of 1, 2, 4 or 8 bytes respectively. Or +Param, +meaning an invalid system call parameter error. Or +Free, meaning an invalid or mismatching free. +Overlap, meaning a src/dst +overlap in memcpy() or a similar function. Last but not least, +you can suppress leak reports with Leak. Leak suppression was +added in valgrind-1.9.3, I believe. +

+The extra information line: for Param errors, is the name of the offending +system call parameter. +No other error kinds have this extra line. +

+The first line of the calling context: for Value and Addr errors, it is either +the name of the function in which the error occurred, or, failing that, the +full path of the .so file or executable containing the error location. For +Free errors, is the name of the function doing the freeing (eg, +free, __builtin_vec_delete, etc). For Overlap +errors, is the name of the function with the overlapping arguments (eg. +memcpy(), strcpy(), etc). +

+Lastly, there's the rest of the calling context. +

3.5  Details of Memcheck's checking machinery