Insure++ 3.1 Release Notes

for users of previous versions of Insure++

There have been some significant changes in certain areas of Insure++. This document will cover some of the highlights, but you should consult the Insure++ manuals for complete documentation.

1. The move from `.insight` files to `.psrc` files.

This change was made to better integrate ParaSoft's growing list of software development tools. All ParaSoft tools now use the same configuration files, which are called .psrc. These files behave in exactly the same way as .insight files did, but allow options for multiple tools. The example below illustrates the change.

With earlier versions of Insure++, if you wanted to set your compiler to use CC, you would add the option

	compiler CC

to a file called .insight. This method is still supported in Insure++ 3.1, but will not be in future releases, so we strongly encourage you to convert your .insight files into .psrc files with this release. The new method of setting the compiler is very similar. You would add the option

	insure++.compiler CC

to a file called .psrc. Similarly, if you wanted to set the compiler CodeWizard uses, you would add the option

	codewizard.compiler CC

to the same .psrc file. The option

	compiler CC

in a .psrc file now has a different meaning - it tells all ParaSoft tools to use CC as the compiler. To avoid confusion, unless you definitely want to use the same option across multiple tools, you should always use the tool name prefix, e.g. insure++, codewizard, insra.

Another change relating to .psrc options is in how to control whether the option applies at compile time, runtime, or both. The following section shows both the old and new methods.

Several of the Insure++ options have effects during both compilation and program execution. When the option is active is controlled by an extra qualifier keyword as shown in the examples below.

	suppress <runtime> READ_NULL		Insure++ 3.0.1 and earlier
	insure++.runtime.suppress READ_NULL	Insure++ 3.1

suppresses errors in the READ_NULL category during program execution. An error in this category detected during compilation would still be reported. Similarly,

	suppress <compile> BAD_PARM		Insure++ 3.0.1 and earlier
	insure++.compile.unsuppress BAD_PARM	Insure++ 3.1

enables the display of this error category during compilation, but not during program execution. Compile time options also apply at link time. If you wish to apply the same option to both compilation and execution, simply omit the qualifier, e.g.

	suppress <all> READ_NULL		Insure++ 3.0.1 and earlier
	insure++.suppress EXPR_NULL		Insure++ 3.1

2. New memory leak summary report options

Memory leak summary reports have been significantly improved by giving the user additional flexibility.

Old-style:

	summarize [sorted|unsorted] [detailed] [leaks|outstanding]*

Sorting was done by location of the allocation (independent of the stack trace), and detailed meant do not combine similar entries.

New-style:

	insure++.summarize [leaks|outstanding]*

This has the same meaning, but sorted, unsorted, and detailed are dropped in favor of new options:

	LeakCombine [none|trace|location]
	LeakSort    [none|location|frequency|size]
	LeakTrace   [on|off]

LeakCombine tells Insure to combine leaks with the same given attribute. For example, the old default was to combine only when sorting and not showing stack traces, in which case we combine by location. The new default will be "leakcombine trace", which means blocks with exactly the same stack trace will be combined.

LeakSort tells Insure how to sort the leaks after combining, if any. Earlier versions of Insure++ sorted only by location. Now the user can choose to sort by location, block size, or full allocation trace.

LeakTrace tells Insure whether or not to show a full stack trace, if possible.

In summary, the following table gives the old-style options in the first column along with their new-style equivalents in the right-hand three columns:

summarize	Combine	Sort	Trace
`leaks (==> sorted)`	`location`	`location`	`off`
`detailed leaks`	`none`	`location`	`on`
`unsorted leaks`	`none`	`none`	`off`
`detailed unsorted leaks`	`none`	`none`	`on`
`the new default is:`	`trace`	`size`	`on`

i.e. the new default is the equivalent to the following three options:

	insure++.LeakCombine trace
	insure++.LeakSort size
	insure++.LeakTrace on

To try out the new-style leak summary reports, simply add the option

	insure++.summarize leaks

to your .psrc file and run your Insured program again.

3. LeakTool

LeakTool allows even more powerful processing of Insure output, particularly memory leak summary reports. It provides the ability to sort and filter the leaks reported so you end up with a report of only leaks in which you are immediately interested. Because LeakTool works with both text output and Insra report files, it also allows the conversion to and from text and Insra-format report files.

The LeakTool man page is included with the other Insure++ man pages as well as in the User's Guide.

4. Delaying the freeing of blocks

The new option

	insure++.free_delay [0|1|2|3|...|119|...]

controls how long the Insure++ runtime holds onto "free'd" blocks before allowing them to be reused. This is not necessary for error detection, but can be useful in modifying the behavior of your program for stress-testing. The number represents how many free'd blocks are held back at a time - large numbers limit memory reuse, and 0 maximizes memory reuse. Please note that this option is only active if malloc_replace was on during linking. The default setting is 119.

5. Stressing `realloc`

The new option

	insure++.realloc_stress [on|off]

tells Insure whether to force all calls to realloc to cause the block in question to move. This can be useful in triggering certain kinds of bugs where the possibility of realloc changing addresses was not considered. This option is on by default.