Getting started with Purify

What it is?

Purify is a development tool from Pure-Atria software which they graciously donated to Stanford for academic use. It checks your program at run-time for many common memory errors, such as accessing freed meomry, overflow and underflow of memory regions, use of unitialized addresses, and so on. Purify works by instrumenting your compiled code with additional error-checking. When you run that new version of your executable with the extra checks, Purify will report what errors were caught. Purify can be helpful in tracking down those difficult-to-find memory errors and can find lurking errors you didn't even know existed.

Setup

To use Purify, you will have to run a script to set up your environment. For those running csh and its variants, you should execute the following command:

% source /usr/pubsw/etc/rational/purifyplus_setup.csh

For sh and its variants, the command is:

% source /usr/pubsw/etc/rational/purifyplus_setup.sh

To save yourself the trouble of having to do this every time you log on, you can add the above command line to your .cshrc.

Compiling and running with Purify

The makefile included with the 143 project starter files should already be set up with a purify target, accessible via the command:

% make pure

This will compile your code and create a new executable with a ".purify" extension that has been instrumented with all the extra checks. Run pp1.purify the same as you would run the non-purified program. The memory usage and errors found during execution will be written to the file purify.log in your directory. You can read through this file to see what Purify has found.

Interpreting the purify.log file

After running a purify-instrumented executable, the purify.log file will contain the report of any memory access errors that were detected. Each error is identified with a TLA (three-letter-acronym) such as ABR (array bounds read -- attempt to read past the end of an allocated region) or FMW (free memory write -- attempt to write to freed memory). Each error usually includes a backtrace for where the memory was originally allocated and the backtrace at the time of the access error. By examinng your code at those locations and looking for an error of the specified type, you can usually sort out what the underlying problem is and fix it. I have seen Purify get things wrong in only extremely unusual and rare circumstances, so if it says you have an error, you almost certainly do.

For more details on the type of errors reorted by Purify, interpreting its output, and controlling advanced features, refer to the Purify man page. Here is a version of the Purify man page converted to HTML.

Problems with getting a Purify license

You may encounter an error obtaining a license. If this is the case, you will get a message like:

Purify: Error: Couldn't get a license. Exiting.
To run the program with Purify functionality disabled,
use the command
    (csh) setenv PURIFYOPTIONS "-continue-without-license=yes $PURIFYOPTIONS"
    (ksh) PURIFYOPTIONS="-continue-without-license=yes $PURIFYOPTIONS"; export PURIFYOPTIONS

This means you forgot to do the setup above.

Let us know if you have other questions!