Sun Studio 12 Update 1: Debugging a Program With dbx

Suppressing Errors

Runtime checking provides a powerful error suppression facility that allows great flexibility in limiting the number and types of errors reported. If an error occurs that you have suppressed, then no report is given, and the program continues as if no error had occurred.

You can suppress errors using the suppress command (see suppress Command).

You can undo error suppression using the unsuppress command (see unsuppress Command).

Suppression is persistent across run commands within the same debug session, but not across debug commands.

Types of Suppression

The following types of suppression are available:

Suppression by Scope and Type

You must specify which type of error to suppress. You can specify which parts of the program to suppress. The options are:

Option  

Description  

Global 

The default; applies to the whole program. 

Load Object 

Applies to an entire load object, such as a shared library, or the main program. 

File 

Applies to all functions in a particular file. 

Function 

Applies to a particular function. 

Line 

Applies to a particular source line. 

Address 

Applies to a particular instruction at an address. 

Suppression of Last Error

By default, runtime checking suppresses the most recent error to prevent repeated reports of the same error. This is controlled by the dbx environment variable rtc_auto_suppress. When rtc_auto_suppress is set to on (the default), a particular access error at a particular location is reported only the first time it is encountered and suppressed thereafter. This is useful, for example, for preventing multiple copies of the same error report when an error occurs in a loop that is executed many times.

Limiting the Number of Errors Reported

You can use the dbx environment variable rtc_error_limit to limit the number of errors that will be reported. The error limit is used separately for access errors and leak errors. For example, if the error limit is set to 5, then a maximum of five access errors and five memory leaks are shown in both the leak report at the end of the run and for each showleaks command you issue. The default is 1000.

Suppressing Error Examples

In the following examples, main.cc is a file name, foo and bar are functions, and a.out is the name of an executable.

Do not report memory leaks whose allocation occurs in function foo.


suppress mel in foo

Suppress reporting blocks in use allocated from libc.so.1.


suppress biu in libc.so.1

Suppress read from uninitialized in all functions in a.out.


suppress rui in a.out

Do not report read from unallocated in file main.cc.


suppress rua in main.cc

Suppress duplicate free at line 10 of main.cc.


suppress duf at main.cc:10

Suppress reporting of all errors in function bar.


suppress all in bar

For more information, see suppress Command.

Default Suppressions

To detect all errors, runtime checking does not require the program be compiled using the- g option (symbolic). However, symbolic information is sometimes needed to guarantee the correctness of certain errors, mostly rui errors. For this reason certain errors, rui for a.out and rui, aib, and air for shared libraries, are suppressed by default if no symbolic information is available. This behavior can be changed using the -d option of the suppress command and unsuppress command.

The following command causes runtime checking to no longer suppress read from uninitialized memory (rui) in code that does not have symbolic information (compiled without -g):


unsuppress -d rui

For more information, see unsuppress Command.

Using Suppression to Manage Errors

For the initial run on a large program, the large number of errors might be overwhelming. It might be better to take a phased approach. You can do so using the suppress command to reduce the reported errors to a manageable number, fixing just those errors, and repeating the cycle; suppressing fewer and fewer errors with each iteration.

For example, you could focus on a few error types at one time. The most common error types typically encountered are rui, rua, and wua, usually in that order. rui errors are less serious (although they can cause more serious errors to happen later). Often a program might still work correctly with these errors. rua and wua errors are more serious because they are accesses to or from invalid memory addresses and always indicate a coding error.

You can start by suppressing rui and rua errors. After fixing all the wua errors that occur, run the program again, this time suppressing only rui errors. After fixing all the rua errors that occur, run the program again, this time with no errors suppressed. Fix all the rui errors. Lastly, run the program a final time to ensure no errors are left.

If you want to suppress the last reported error, use suppress -last.