Tool Mentor: Detecting Run-Time Errors Using Rational Purify and Rational PurifyPlus (UNIX)

Tool Mentors > Rational Purify Tool Mentors > Detecting Run-Time Errors Using Rational Purify and Rational PurifyPlus (UNIX)

Purpose

This tool mentor provides an overview of how to use Rational Purify® to find run-time errors in your programs.

PurifyPlus is a Rational product that includes Purify functionality.

To learn more about Purify and for a tutorial-style introduction, read the Installing and Getting Started manual for the PurifyPlus product family (UNIX version).

For step-by-step instructions on using Purify and for reference information, see the Purify online Help.

Related Rational Unified Process information:

Activity: Perform Unit Tests, refer to the section titled "Execute Unit Test"
Activity: Implement Test
Activity: Determine Test Results
Activity: Analyze Execution Failures

Overview

Purify detects run-time errors, including memory leaks, both in your own code and in the components your software uses, even when you don't have the source code. It reports memory errors such as array bounds errors, access through dangling pointers, uninitialized memory reads, memory allocation errors, and memory leaks, so you can resolve them before they do any damage.

Tool Steps

To test a program using Purify:

Instrument and run the program with Purify to detect run-time errors
Analyze Purify error messages
Correct the errors and rerun the program

1. Instrument and run the program with Purify to detect run-time errors

The first step in Purify'ing your code is to instrument and run your program.

Just add the word purify to the beginning of your compile/link line. To get the maximum amount of detail in Purify messages, compile your program using the -g debugging option. For example:

% purify cc -g hello_world.c

On IRIX, you can use the above command or you can Purify the executable: purify a.out.

Purify instruments your code by copying your object code and libraries, and using Object Code Insertion (OCI) technology to insert checking instructions before each memory operation. On IRIX, Purify instruments the executable file, then saves the file under a new name.

After instrumentation, run the instrumented program. For example:

% a.out

On IRIX, type: a.out.pure

As you exercise the instrumented program, Purify displays run-time errors in the Purify Viewer. When you exit the program, Purify reports memory leaks.

To gather code coverage data as you Purify your program, add the purecov command after the purify command in your compile/link line. Coverage data shows which parts of your code have and have not been tested.

Tip: In addition to using Purify interactively, you can also incorporate Purify into your test scripts, makefiles, and batch files for automated testing.

For more information, look up the following topics in the Purify online Help index:

basic steps
running programs
makefiles and scripts
purecoverage

2. Analyze Purify error messages

The second step in Purify'ing your code is to analyze the error messages.

Each Purify error message begins with a three-letter acronym that summarizes the message. For example, an ABR is an Array Bounds Read error. For a complete list of Purify error messages and their descriptions, see the Purify online Help.

The condensed outline format of the Purify Viewer makes it easy to scan the error messages, identify the critical errors, and assess the state of your program at a glance. In a large program that generates hundreds of error messages, you can use Purify suppressions to quickly focus on the most critical errors.

Purify messages expand to show detailed diagnostic information such as the function call chain leading to the error and, if you compiled your program using the -g option, Purify pinpoints the exact location of the error in your source code. Because Purify detects access errors at the point where they occur, it helps you identify, understand, and eliminate hard-to-find memory access errors and memory leaks.

You can customize how Purify handles error data. For example, you can specify whether Purify records and displays specific types of messages, and you can specify the length of the function call chain recorded for errors and allocations.

Tip: When you run Purify as part of your nightly tests, you can automatically save Purify output to a view file (.pv) without displaying the Viewer. The following morning, open the saved view file in the Purify Viewer and analyze it as you normally would. Just type: purify -view a.out.pv. You can also save Purify output to a view file from the Viewer when you want to analyze it at a later date or share it with colleagues who have Purify.

For more information, look up the following in the Purify online Help index:

suppressing messages
saving data
view files
options

Using your debugger with Purify

You can run your Purify'd program directly under your debugger so that when Purify finds an error you can investigate it immediately. Alternatively, you can enable Purify's just-in-time (JIT) debugging feature to have Purify start your debugger only when it encounters an error. JIT debugging is useful for errors that appear only occasionally. You can monitor a region of memory for specific kinds of memory accesses by setting a Purify watchpoint on it. Purify watchpoints are faster to use and more convenient than debugger watchpoints.

For more information, look up the following topics in the Purify online Help index:

JIT debugging
watchpoints

Using Purify API functions

You can call Purify API functions from your source code or from you debugger to gain more control over Purify error checking. By calling Purify API functions from your debugger, you get additional control without modifying your source code. You can use Purify API functions to check memory state, and to search for memory and file-descriptor leaks.

For more information, look up the API functions topic in the Purify online Help index.

3. Correct the errors and rerun the program

The third and final step in Purify'ing your code is to correct the errors and rerun the program.

To correct errors, click the Edit tool. Purify opens your source code in your editor at the exact location of the error, ready for correction.

After you correct the error, recompile your program and run it again with Purify. Purify displays the results of the new run in the same Viewer so you can verify your correction by comparing the new results to the previous run.

Repeat this cycle of instrumenting and running the program, and analyzing and correcting errors until your program runs clean.

Using Purify with other Rational Software Tools

Use Purify with Rational PureCoverage to make sure you are Purify'ing all of your code. If your development environment includes a configuration management system such as Rational ClearCase, you can use the Purify toolbar to check files in and out directly from the Purify Viewer. If Rational ClearQuest, Rational Software's defect-tracking tool, is installed at your site and in your path, you can start it directly from the Purify Viewer.

Rational Unified Process