Tools - Purify

Resolving The Problem

Purify is a useful tool for finding memory management problems and other sources of intermittent problems. Purify is somewhat difficult to use. It requires an ability to interpret the potentially thousands of warnings it can produce. It has sometimes been difficult to get a MAS to run properly under Purify. A Purified program will run considerably slower than the actual program. Purify requires a large amount of disk space, e.g., 50 MB. Purify can only find problems in code that gets executed, so it is important to get good coverage with the test data used drive the program under scrutiny.

You must run Purify 4.1 or higher. Versions earlier than 4.1 have problems handling multi-threaded programs. (Purify 4.1 may still have some issues related to multi-threaded programs, so if there is a newer version, go get it.)

The program gets purified in the link step. It does not need to be recompiled only relinked. In your make file you would have something like:

# Purify needs large amounts of disk space.
# Also, if you are going to compile on one machine and try to run on another,
# then the cache needs to be at the same place on both machines. Despite what
# the manual appears to indicate, you can't specify the cache location again at
# run time. (At least this was the case with Purify 4.1.)
CACHE_DIR = /devel/pure-cache

PURIFY = /opt/purify/purify-4.1-solaris2/purify
# The -mark-wrapped-stacks option is undocumented and fixes a bug in Purify
# that causes spurious IPR and IPW messages in threaded applications.
PFLAGS = -mark-wrapped-stacks \
-check-debug-timestamps=no \
-cache-dir=$(CACHE_DIR) \
-always-use-cache-dir=yes \
-max-threads=100

# This redefines the CC macro for all dependencies of the "pure" target.
# "all" is defined to be a dependency below., so "make pure" builds
# a directory purified.
#
# Note:
# - This definition of CC must come after the regular definition.
# - We redefine CC for compiles as well as links because it was easiest,
# but it's a no-op for the compiles. Only links matter.
# - Only the link needs to be redone for a purified build. Objects and
# libraries do not have to be recompiled.
# This is a Solaris make trick. Other platforms may have a similar trick.
pure := CC = $(PURIFY) $(PFLAGS) CC


Where your targets are specified you must have the "all" target first then the "pure" target. This will allow "make pure" to be used to Purify your program.

<suffix rules>

all: <myprogram>

pure: all

# link rule for program
<myprogram> : <dependencies>
$CC $CFLAGS etc

When you run Purify on your program you should see messages on the screen indicating that Purify is instrumenting each module and library linked into your program. If you have a large program with Encina and DCE libraries this may take awhile the first time you Purify.

We have seen problems with Encina programs running under Purify where Purify seems to be confused about the structure of the stack. It reports BSW and BSR warnings as well as IPR and IPW warnings that don't make any sense. An undocumented flag to use (when linking with Purify) to fix this problem is -mark-wrapped-stacks. This corrects a defect in how Purify handles multi-threaded programs. This defect was present in Purify 4.1.

You might also need to use -force-rebuild to get instrumented versions of libraries to be rebuilt.

Before you can run your program you need to set two environment variables:
DISPLAY=<IPaddress>:0
PURIFYOPTIONS='-max-threads=100 -chain-length=10'

(You might not need to set the PURIFYOPTIONS env var if you have these options set in the flags used to relink the program.)

If the DISPLAY isn't set correctly, the program probably won't come up. It is also common to have the DISPLAY set to a host that you are not working at if more than one person is debugging a particular server. The DISPLAY will get opened on the other host and you will think the program isn't running, when it really is. Also, once a DISPLAY is opened it gets reused.

From the Purify display, you can save a Purify run to a file. You view it later with:

purify -view < file name >

Purify categorizes its messages into "fatal", "corrupting", "warning", and "informative". There is an Xdefaults file installed with Purify. If you copy it to the home directory of the server's user, e.g., ~encina/.purify.Xdefaults the different categories of messages will be color coded. "Corrupting" errors are the worst, and will show up in red. These should never be ignored.

Some of the warnings issued by Purify can be ignored. Warnings that occur in DCE or Encina code can typically be ignored (but as the Purify manual reminds us, "Often, errors that appear in library functions are caused by a program's misuse of those functions".

UMRs (Uninitialized Memory Reads) have to be ignored, because there are too many of them to look at.

Purify does not know how to handle programs that write and read to/from shared memory segments. You can safely ignore warnings generated by Encina applications that do shared memory operations. These are IPR warnings early in a program's execution.

Warnings in application code should never be ignored. Make sure you understand why they are being issued.

Small memory leaks from DCE are not a problem. Large heap allocations at the beginning of a program that are never freed can be ignored in the case where the allocated structure is to be used for the entire life of the program.

Purify provides mechanisms for suppressing warnings. (It would be particularly desirable to suppress UMR warnings.) This is done from the Purify display. However, it appears that Purify ignores the .purify files for a MAS.

The IBM Purify web site is at:

http://www.ibm.com/software/rational/