--- title: "Suppressing Errors" layout: default permalink: /page_suppress.html ---

Dr. Memory

Suppressing Errors

If Dr. Memory is reporting numerous errors that appear to be false positives and originate in libraries that are not part of your application, consider using the blocklist and allowlist options to isolate them, which may be more effective than suppressing individual errors. See Application Versus System Library Errors for more information.

To aid in suppressing individual errors, Dr. Memory generates a file named `suppress.txt` alongside the `results.txt` file. To suppress errors from being reported in future runs, edit this file to contain just the errors you wish to suppress. Then pass the file to `drmemory` with the -suppress option:

    drmemory.exe -suppress c:/suppress-custom.txt -- myapp

The suppress.txt generated by Dr. Memory will contain suppression information only for those errors that weren't suppressed using the -suppress option. For each error reported in suppress.txt, there will be two types of call stacks, one showing `<module+offset>` type frames and the other `module!function` type frames. The offset in `<module+offset>` must be a lower-case hexadecimal constant (e.g., `0x4af`) and is the offset from the start of the module. Either type of call stack can be used and it is enough if one of those two is specified. The `module!function` are more general and more robust across different versions of a module.

In order to simplify writing suppressions, callstacks support "*" and "?" wildcards in either the module or function name (or offset for `<module+offset>`). A "*" matches any number of characters of any kind. A "?" matches a single character of any kind. C++ functions should be in their unmangled form. If a literal "*" is desired, a "?" should usually be used instead to avoid the "*" wildcard expansion.

To match any frame at all, use a single "*". To match any module but not any non-module (and thus not match a system call or non-module code, such as generated code), use "*!*".

Callstacks automatically employ prefix matching. Prefix matching means that the callstack in the suppression file is considered a match if it matches the top of any actual callstack during a run. This allows specifying only the first few frames of a callstack and have it match any callstack whose first frames match those frames, regardless of subsequent frames.

A final type of wildcard frame is supported: "...". A callstack frame consisting of the string "..." matches zero or more frames in the callstack.

As a variation on the "..." ellipsis frame, "module!..." matches one or more frames in a given module. Importantly, it will not match zero frames like a plain ellipsis. This form is most useful for suppressing reports through system libraries that are missing symbols, because oftentimes such reports can be identified by the way they call back and forth across system library boundaries.

Suppression files can have empty lines and comment lines (begining with #). There should be no leading white space for the actual suppression information. Suppressions should not end with "...", which is unnecessary due to the implicit prefix matching.

A suppression can be given an identifier with a `name=` line after the error type line. Suppressions that were matched are printed in the results file with a count of how many unique callstacks were matched. Duplicate callstacks are not included. Here is an example:

LEAK
name=bug #456 (deliberately leaked object)
mylib.dll!LeakMe
mylib.dll!*

On Windows, for unaddressable accesses and uninitialized reads, a suppression can be further restricted by the actual instruction involved. The instruction is printed out in an error report in a `Note:` field. For example:

Error #8: UNADDRESSABLE ACCESS beyond heap bounds: reading 0x001338a8-0x001338ac 4 byte(s)
...
Note: instruction: mov (%eax) -> %eax

A suppression can contain an `instruction=` line after the error type line which will be matched against this note field. It can contain wildcards. Here is an example:

UNINITIALIZED READ
name=bug #123 (deliberate uninitialized read to generate random number)
instruction=test * $0x00000?00
myranlib.dll!GenRanHelper*
myranlib.dll!GenRan*

For users with existing Valgrind Memcheck suppression files, Dr. Memory supports Valgrind-style suppressions, but not with mangled C++ symbols. On Linux and Mac, a script called `valgrind2drmemory.pl` is provided in the bin directory that can be used to convert a legacy Valgrind suppression file to the Dr. Memory format. It uses heuristics to convert mangled C++ symbols that contain wildcards and may not succeed on complex types (it prints a warning for those it fails on). Use it like this:

bin/valgrind2drmemory.pl /path/to/old-supp-file /path/to/new-drmem-towrite

The Dr. Memory suppression format is more powerful then the Valgrind format and matches the Windows module!function standards used by other tools. We recommend converting to the Dr. Memory format from a legacy format.

Another method of ignoring errors is to filter the reported errors to focus on particular source files or particular libraries, using Dr. Memory's allowlisting options. See Application Versus System Library Errors for further information on allowlists.

A final method of ignoring uninitialized reads, in particular, for an entire library is described in Eliminating Uninitialized Read Checks By Library.

To get more information on what errors are being suppressed, run with `-log_suppressed_errors`. All suppressed reports will be printed to the global logfile.

Dr. Memory comes with a set of default suppressions to avoid certain known false positives (and known true positives, i.e., actual bugs) in the C and C++ libraries and other locations. These can be disabled with the option -no_default_suppress.