NAME
purify - instrument a program to detect run-time memory
corruption errors and memory leaks
SYNOPSIS
purify [-option ...] $(CC) $(CFLAGS) -o program $(OBJS) $(LIBS)
purify -view [program] [saved.pv]
DESCRIPTION
Purify intercepts every memory access by inserting instruc-
tion sequences into the user's executable program before
each load and store machine code instruction. These
instruction sequences make it possible for Purify to detect
memory corruption just before it happens, even if it occurs
in a shared library or a third-party library. Purify also
finds memory leaks - memory that has been allocated but can
no longer be accessed because there are no pointers to it.
Purify detects:
o Reading or writing beyond the bounds of an array.
o Reading or writing freed memory.
o Freeing memory multiple times.
o Reading and using uninitialized memory.
o Reading or writing through null pointers.
o Overflowing the stack by recursive function calls.
o Reading or writing the first page of memory.
o Having memory leaks.
o Leaving open file descriptors.
o Reading or writing memory addresses on which a watch-
point has been set.
Setting Up
Purify is typically loaded from CD-ROM, and then installed
using the pure_install command. You will need a license
certificate with a valid password; enter the information
requested exactly as printed on the certificate. For more
information, see the ``Installation and Licensing Guide.''
To use Purify, create a symbolic link from where purify is
installed (purifyhome/purify) to /usr/local/bin/purify (or
some other directory on each user's $PATH):
example% ln -s purifyhome/purify /usr/local/bin/purify
Purify follows this symbolic link to find the other files it
needs in the installation directory.
Under Solaris 2.x the additional program purifyhome/repurify
should also be made available:
example% ln -s purifyhome/repurify /usr/local/bin/repurify
Alternatively, add purifyhome to each user's $PATH.
Building
Add the word purify to the beginning of the link line in
your Makefile. For example:
program: $(OBJS)
purify [-option ...] $(CC) $(CFLAGS) -o program \
$(OBJS) $(LIBS)
Purify modifies the object code at link time to produce an
equivalent program which has additional error checking
instructions built in. The -options specified on the com-
mand line are Purify options to customize its operation.
Running
The Purify'd program is run exactly as the original program.
A Purify Viewer window will be created, and error messages
will be displayed as Purify detects various conditions. The
messages initially appear in the Viewer as one-line sum-
maries, which may be expanded and collapsed by clicking on
the arrow glyph to the left. Some messages may have sub-
items which may be further expanded for more detail.
When you re-run the program, it will try to re-connect to
the existing Purify Viewer, displaying its messages below
any previously displayed. If the Viewer has exited, it will
create a new one.
Alternatively, messages may be output in ASCII, either to a
log file, or to the standard error stream. This is the
default if an X window cannot be created, or if you use the
option -windows=no. You can also request ASCII output by
using the Purify options -log-file=filename or
-log-file=stderr. Additionally, you can use the
-mail-to-user option to send an ASCII report to a user or
list of users.
Viewing saved data
You can save the messages output by Purify either using the
"Save as..." item from the "File" menu of the Purify Viewer,
or using the -view-file option at run-time to save directly
to a file without creating a Viewer. The messages are
stored in a compact binary format called Purify View format.
We recommend you use the extension .pv for such files.
To view saved .pv files after a run has finished, use the
command:
example% purify -view [-option ...] saved.pv
This displays the messages in the Viewer for inspection just
as if the program had just been run. Furthermore, the new
Viewer listens for connections from other runs of the same
application, and displays messages from those runs too.
To invoke a Purify Viewer just to listen for connections
from an application without displaying saved .pv files, use
the command:
example% purify -view [-option ...] program
This form of the command may be useful if you wish to start
a Viewer on one X display while running the application
itself on another X display.
Debugging
Purify has many features that extend the power of your
debugger. The most important is the function
purify_stop_here(). If you set a breakpoint on this func-
tion, your debugger will stop on every Purify error message,
right after the message is displayed and before the error
actually occurs in your program:
(dbx) stop in purify_stop_here
(gdb) break purify_stop_here
(xdb) b purify_stop_here
This allows you to look at the state of your program before
the error actually occurs to investigate its cause. Note
that you should never call purify_stop_here() directly from
your program; only set a breakpoint on it.
Memory Leaks
Memory leak analysis is performed when a program exits. You
can also call the Purify function purify_new_leaks() at
other times from a debugger while the program is stopped:
(dbx) print purify_new_leaks()
The memory leak message reports blocks on the heap which are
no longer accessible through any pointer, which have been
leaked since the program started or since the last call to
purify_new_leaks(). Other functions can be invoked to
profile non-leaked blocks, or to list all leaks or blocks
instead of just those generated since the last call.
The memory description functions purify_describe() and
purify_what_colors() are also useful in debugging situa-
tions:
(dbx) print purify_describe(addr)
(dbx) print purify_what_colors(buf, sizeof(buf))
File descriptors in use
File descriptor analysis is also performed at program exit,
or when you call the function purify_all_fds_inuse():
(dbx) print purify_all_fds_inuse()
The file descriptors message shows which file descriptors
are currently open, and additional information about where
and how they were opened.
Watchpoints
A watchpoint may be set on a memory address by invoking the
function purify_watch():
(dbx) print purify_watch(&counter)
Note that watchpoints are set on fixed addresses, and if
such an address lies on the dynamic heap space or in the
stack space (automatic variables), the watchpoint will refer
to different data objects as the heap is reallocated or as
functions are called and return, leaving automatic variables
on the stack. By default, the watchpoint is set on the four
byte word at the indicated address, for write accesses only;
other functions set watchpoints of different sizes and
access modes, or remove watchpoints.
Watchpoints are automatically saved to the file
program.watchpoints in the current directory and are thus
preserved from one run to the next. If the program is
relinked (and is newer than the watchpoints file), the
watchpoints file is ignored.
Suppression
From the Purify Viewer, you can suppress errors by class and
location. Select the error to be suppressed and then click
the suppress icon or the "Suppress" item from the "Actions"
menu. Complete the dialog which appears to suppress the
message. Suppressions of this form are local to the ses-
sion. You can also make suppressions permanent by copying
the line which appears near the bottom of the suppression
dialog into a file named .purify in the directory where the
program lives, in directory $HOME, or in purifyhome. Files
named .purify.sunos4, .purify.solaris2, or .purify.hpux are
also read for suppressions on the corresponding platforms.
Purify and PureCoverage
Purify is designed to work with PureCoverage to collect code
coverage information at the same time as monitoring the code
for access errors and memory leaks.
To create a program instrumented by Purify and PureCoverage,
use a command like:
purify [-option ...] purecov [-option ...] \
$(CC) $(CFLAGS) -o program $(OBJS) $(LIBS)
Message Types
Each run of a Purify'd program generates a sequence of mes-
sages.
Start-up message
The first message in a run is the configuration message. It
tells you the full name of the program, the process ID, and
the date the run started, the version of Purify in use, the
options in force, the command line used, and various other
information.
MESSAGE DESCRIPTION SEVERITY
ABR Array bounds read WARNING
An ABR message indicates that your program is about to read
a value from before the beginning or after the end of an
allocated block.
Common causes include:
o making an array too small (e.g. failing to account for
the terminating NULL in a string);
o forgetting to multiply by sizeof(type) when allocating
for an array of objects;
o using an array index too large or negative;
o failing to NULL terminate a string; or
o being off-by-one in copying elements up or down an
array.
ABW Array bounds write CORRUPTING
An ABW message indicates that your program is about to write
a value to before the beginning or after the end of an allo-
cated block.
Common causes include:
o making an array too small (e.g. failing to account for
the terminating NULL in a string);
o forgetting to multiply by sizeof(type) when allocating
for an array of objects;
o using an array index too large or negative;
o failing to NULL terminate a string; or
o being off-by-one in copying elements up or down an
array.
BRK Brk or sbrk called outside malloc CORRUPTING
A BRK message indicates that your program is using brk() or
sbrk() directly to allocate memory. Use of brk() or sbrk()
is incompatible with the use of most implementations of mal-
loc() and free().
BSR Beyond stack read WARNING
A BSR message indicates that a function in your program is
about to read beyond the current stack pointer. The data
beyond the stack pointer is subject to change without
notice, for example if your program takes a context switch
or a signal; thus the value read by this access is not reli-
able.
A common cause of a BSR is a function returning a pointer to
a local variable that has gone out of scope. If the caller
attempts to use that variable, this error may result. To
keep the value valid after the called function has returned,
make such variables static.
BSW Beyond stack write WARNING
A BSW message indicates that a function in your program is
about to write beyond the the stack pointer.
Note: unlike other write errors such as ABW, this is not a
corrupting error, since it is always legal to write a value
beyond the end of the stack. However, values beyond the
current stack pointer are subject to change without notice;
for example, if your program takes a context switch or a
signal, then the value written by this access may not be
reliably re-read.
A common cause of a BSW is a function returning a pointer to
a local variable that has gone out of scope. If the caller
attempts to use that variable, this error may result. To
keep the value valid after the called function has returned,
make such variables static.
Note: Some compilers utilize a side-effect of the instruc-
tion to write the FSR register to synchronize the FPU with
the main processor. In such cases, storing the value below
the stack pointer is reasonable, since the actual value is
not relevant, only the side-effect of the store. If you see
a BSW from floating point computation library routines, it
is probably safe to suppress it.
COR Fatal core dump FATAL
A COR message indicates that your program has received a
signal that would normally generate a core dump. COR indi-
cates a fatal error.
The direct cause is usually a segmentation violation
(attempting to address a page of memory which has not been
mapped), or a bus error (attempting to address memory with a
pointer not aligned properly for the size of the datum being
addressed). Common causes include:
o indirecting through a NULL pointer, which usually gen-
erates a segmentation violation;
o dereferencing a pointer obtained by performing arith-
metic operations on a pointer cast to an integer, which
may cause a bus error; or
o using an uninitialized or completely random value as a
pointer, which may cause a bus error, if the address is
unaligned, or a segmentation violation, if the address
points to non-existent memory.
FIU File descriptor in use INFORMATIONAL
At program exit, or when you call one of these API func-
tions:
purify_new_fds_inuse();
purify_all_fds_inuse();
a collection of FIU messages is generated. Each message
describes what is known about the origin of one open file
descriptor. If you see multiple file descriptors for the
same file, or from the same call chain in the program, you
should be concerned that you have a file descriptor leak,
and your program may run out of file descriptors.
FMM Freeing mismatched memory WARNING
An FMM message indicates that your program is deallocating
memory using a function that does not match the function
used to allocate it. Matching functions include:
malloc / free
new / delete
new[] / delete[]
This type of error can cause object destructors to run an
incorrect number of times.
FMR Free memory read WARNING
An FMR message indicates that your program is about to read
from memory within the heap which is not in or near a
currently allocated block. This could be a dangling pointer
to a block of memory that has already been freed (caused by
retaining the pointer too long, or freeing the memory too
soon). Alternatively, it could be the result of indexing
very far off the end of a valid block, or using a completely
random pointer which happens to fall within the heap seg-
ment.
FMW Free memory write CORRUPTING
An FMW message indicates that your program is about to write
to memory within the heap which is not in or near a
currently allocated block.
This could be a dangling pointer to a block of memory that
has already been freed (caused by retaining the pointer too
long, or freeing the memory too soon). Alternatively, it
could be the result of indexing very far off the end of a
valid block, or using a completely random pointer which hap-
pens to fall within the heap segment.
FNH Freeing non-heap memory CORRUPTING
An FNH message indicates that your program is calling free()
with a memory address that is not in the heap (memory in
stack, data or bss).
Look for pointers to strings or objects which are normally
allocated on the heap being initialized with pointers to
constants in the program data or text segments, or on the
stack. Attempts to free such addresses cause this error.
FUM Freeing unallocated memory CORRUPTING
An FUM message indicates that your program is trying to free
unallocated memory (duplicate free() or free of bad heap
pointer).
A common problem is lack of clear ownership of heap objects.
Only the owner should free heap objects.
If there are many references to a heap object with no one
reference being clearly the longest lived, the object refer-
enced may have a reference count. Failure to maintain the
reference count properly may also lead to this error.
IPR Invalid pointer read FATAL
An IPR message indicates that your program is trying to read
from an invalid address. A segmentation violation will usu-
ally result.
IPR messages are similar to NPR and ZPR messages, except
that they indicate an invalid reference to memory outside of
the zero'th page.
IPW Invalid pointer write FATAL
An IPW message indicates that your program is trying to
write to an invalid address. A segmentation violation will
usually result.
IPW messages are similar to NPW and ZPW messages, except
that they indicate an invalid reference to memory outside of
the zero'th page.
MAF Memory allocation failed INFORMATIONAL
An MAF message indicates that malloc() has failed - you have
run out of swap space for the heap to grow. After the mes-
sage is delivered, malloc() returns NULL in the normal
manner. MAF is an informational message about memory.
Ideally, programs should handle out-of-swap conditions
gracefully, but often do not. If your program next gen-
erates an NPR, NPW, ZPR, or ZPW, and then a COR, then a
caller of malloc() has failed to check the return status and
is dereferencing the null pointer.
MIU Memory in use INFORMATIONAL
An MIU message describes heap memory that you are currently
using (memory to which there is a pointer). Use one of
these API functions to generate a list of memory blocks in
use:
purify_new_inuse();
purify_all_inuse();
A list of memory blocks in use is generated at exit only if
the option -inuse-at-exit=yes is set, or when one of these
API functions is called:
purify_new_inuse();
purify_all_inuse();
MLK Memory leak WARNING
An MLK message describes heap memory that you have leaked.
There are no pointers to this block, or to anywhere within
this block. A list of leaked memory blocks is generated at
exit (unless the option -leaks-at-exit=no is set), or when
one of these API functions is called:
purify_new_leaks();
purify_all_leaks();
A memory leak is caused when the last pointer referencing a
block of memory is cleared, changed, or goes out of scope.
If the section of the program where the memory is allocated
and leaked is executed repeatedly, you may eventually run
out of swap space; this is a serious problem for long-
running interactive programs.
Memory which is allocated once, referenced by a pointer
(perhaps static or global), and never freed, is not a leak.
Since it is allocated only once, you cannot run out of
memory during extended use of the program.
Note: if you call exit(), any blocks of memory referenced by
local variables in the functions above exit() on the stack
continue to be in scope, and anchor blocks of memory which
are not reported as leaks. However, if instead you return
from main(), all local variables go out of scope, and you
may see additional memory leaks reported.
To track memory leaks, examine the call chain where the
memory was allocated, and try to figure out where it should
have been freed.
Another technique is to call purify_new_leaks() regularly
while the program is running to see which program interac-
tions cause the leak to appear.
MRE Malloc re-entered CORRUPTING
An MRE message indicates that a re-entrant call to malloc(),
free(), or a related function has been made while already in
a call to one of these functions. Since most default mal-
loc() implementations are not re-entrant, this will likely
cause problems, unless you are using an implementation known
to tolerate re-entrant calls.
A possible cause of MRE errors is calling printf() within a
signal handler. If the signal interrupts while in a call to
a memory allocation function, it is possible for printf() to
attempt to call malloc() itself to obtain an output buffer.
Note that a number of C library functions call malloc() as a
side effect. These should be avoided in interrupt/signal
handlers.
Other possible causes include using malloc() within threaded
programs in an unsafe way, or using longjmp() indiscrim-
inately from a signal handler for a signal delivered during
a call to malloc().
See the malloc manual page, the POSIX standard, or Advanced
Programming in the UNIX Environment, Section 10.6, by W.R.
Stevens.
MSE Memory segment error WARNING
An MSE message indicates that you are attempting to address
a piece of memory which spans potentially non-contiguous
segments of memory. The segments identified include the
text segment, the data segment, the heap, the stack, and
memory mapped regions.
One common cause is calling a string or block-copy function
with too large a size or count on a block of memory near the
end of the data segment, such that the access spills into
the heap. For example, calling strlen() for a string not
properly terminated may have this effect.
Another likely cause is incorrect size calculation for read
or write buffers, leading to requests for transactions with
negative or huge sized buffers.
NPR Null pointer read FATAL
An NPR message indicates that your program is trying to read
from address zero (read from a NULL pointer). A
segmentation violation will usually result.
One common cause is failure to check return status for a
function expected to return a pointer to a string or an
object. If the function returns NULL on failure, use of the
NULL pointer leads to this error.
NPW Null pointer write FATAL
An NPW message indicates that your program is trying to
write to address zero (store to a NULL pointer). A segmen-
tation violation will usually result.
One common cause is failure to check return status for a
function expected to return a pointer to a string or an
object. If the function returns NULL on failure, use of the
NULL pointer leads to this error.
PAR Bad function parameter WARNING
A PAR message indicates that your program has called a com-
mon library function, such as write(), with a bad parameter.
Typically Purify warns about bad parameters which involve
pointer abuse, such as passing NULL as the buffer to read or
write.
PLK Potential memory leak WARNING
A PLK message describes heap memory that you may have
leaked. There are no pointers to the start of the block,
but there exist pointers pointing somewhere within the
block.
Memory in use may sometimes appear as a PLK if the pointer
returned by malloc() is offset. A common cause is referenc-
ing a substring within a large string. Another example,
when a pointer to a C++ object is cast to the second or
later base class of a multiply inherited object, it is
offset past the other base class objects.
Leaked memory may sometimes appear as a PLK, if some non-
pointer integer within the program space, when interpreted
as a pointer, points within an otherwise leaked block of
memory. Fortunately, this is rather rare.
Inspection of the code should usually easily differentiate
between these causes of PLK messages.
SBR Stack array boundary read WARNING
An SBR message indicates that your program is about to read
across stack frame boundaries (which divide the areas of
memory used for local variables of one function from those
of another). This is similar to an ABR, but concerns a
local variable instead of a malloc'd block.
Common causes include:
o making an automatic array too small (e.g. failing to
account for the terminating NULL in a string);
o forgetting to multiply by sizeof(type) when allocating
for an array of objects;
o using an array index too large or negative;
o failing to NULL terminate a string; or
o being off-by-one in copying elements up or down an
array.
SBW Stack array boundary write CORRUPTING
An SBW message indicates that your program is about to write
across stack frame boundaries (which divide the areas of
memory used for local variables of one function from those
of another). This is similar to an ABW, but concerns a
local variable instead of a malloc'd block.
Common causes include:
o making an automatic array too small (e.g. failing to
account for the terminating NULL in a string);
o forgetting to multiply by sizeof(type) when allocating
for an array of objects;
o using an array index too large or negative;
o failing to NULL terminate a string; or
o being off-by-one in copying elements up or down an
array.
SIG Fatal signal handled INFORMATIONAL
A SIG message indicates that your program has received a
signal, such as SIGINT generated by a control-C. By
default, Purify only notifies you about signals that nor-
mally terminate the program.
SOF Stack overflow error WARNING
An SOF message indicates that your program has overflowed
the stack, probably due to runaway recursion.
Purify reports an SOF when the stack passes an internal
limit, which may be set using the -stack-limit option. Set
this limit to at least 100k before the real end of the
stack, since Purify itself will use some stack beyond the
limit in order to report the problem. This 100k includes
the space for the dynamic linker.
The default value is set 100k before the stack limit imposed
by the system (which may be set and examined using the
"limit stack" shell command).
UMC Uninitialized memory copy WARNING
A UMC message indicates that an uninitialized value is being
copied from one memory location to another (e.g. an assign-
ment). Such copies are normally harmless, representing
copying of padding fields in structures, for example.
By default, this warning message is suppressed in the global
.purify file because it may generate a lot of output.
You can use UMC messages if you are getting a UMR message on
a variable to which an assignment has clearly been made.
The UMC messages will help you track down the sequence of
copies which propagate the uninitialized value into the
variable on which the UMR is being reported.
Enable UMC reporting by adding a line such as the following
in a .purify file in the same directory as the program:
unsuppress umc *
UMR Uninitialized memory read WARNING
A UMR message indicates that your program is about to read
uninitialized memory.
Often, uninitialized memory will be zero, especially during
unit testing. Your program will seem to perform correctly
but the UMR may eventually cause incorrect behavior.
Note that it is common, and correct behavior, for a program
to copy uninitialized data from one variable to another. A
frequent case is during structure assignment when the struc-
ture being copied has inaccessible padding bytes. For this
reason, Purify does not report UMRs on copies, but instead
propagates the uninitialized status to the destination of
the copy.
If you are getting a UMR message on a variable to which an
assignment has clearly been made, it is probably because the
value assigned was itself a copy of uninitialized data. You
can enable the normally suppressed UMC (uninitialized memory
copy) reporting to help track down such problems.
Enable UMC reporting by adding a line such as the following
in a .purify file in the same directory as the program:
unsuppress umc *
Purify may attribute a UMR to the closing brace of a func-
tion. This is probably because one or more execution paths
did not assign a return value for the function. Please
check all possible return locations.
PMR Partial uninitialized memory read WARNING
A PMR message indicates that your program is about to read a
region of memory which has been partly initialized, but
which is partly uninitialized.
Normally, accessing memory which is partially uninitialized
will report a UMR (uninitialized memory read). But if you
specify the Purify option "-report-pmrs" then Purify will
report this kind of access as a PMR instead of a UMR.
Often, uninitialized memory will be zero, especially during
unit testing. Your program will seem to perform correctly
but the PMR may eventually cause incorrect behavior.
The reason to distinguish a PMR from a UMR is so you can
suppress the PMRs in your program. Sometimes you can not
avoid a PMR, as when a struct which has pad bytes is passed
by value as an argument to a function.
WPR Watchpoint read INFORMATIONAL
A WPR message indicates that your program is about to read
from memory that has a read-type watchpoint on it. WPR is
an informational message about memory.
WPW Watchpoint write INFORMATIONAL
A WPW message indicates that your program is about to write
to memory that has a write-type watchpoint on it. WPW is an
informational message about memory.
WPF Watchpoint free INFORMATIONAL
A WPF message indicates that your program is about to free a
block of memory containing a watchpoint. WPF is an informa-
tional message about memory.
WPM Watchpoint malloc INFORMATIONAL
A WPM message indicates that your program is about to malloc
a block of memory containing a watchpoint. WPM is an infor-
mational message about memory.
WPN Watchpoint function entry INFORMATIONAL
A WPN message indicates that your program has just entered a
function that is allocating local variables on the stack in
watched memory. WPN is an informational message about
memory.
WPX Watchpoint function exit INFORMATIONAL
A WPX message indicates that your program has exited a func-
tion that had allocated local variables on the stack in
watched memory. WPX is an informational message about
memory.
ZPR Zero page read FATAL
A ZPR message indicates that your program is trying to read
from the zeroth page of memory. A segmentation violation
will usually result.
One common cause is failure to check return status for a
function expected to return a pointer to a structure or an
object. If the function returns NULL on failure, accessing
a structure field from the NULL pointer leads to this error.
ZPW Zero page write FATAL
A ZPW message indicates that your program is trying to write
to the zeroth page of memory. A segmentation violation will
usually result.
One common cause is failure to check return status for a
function expected to return a pointer to a structure or an
object. If the function returns NULL on failure, accessing
a structure field from the NULL pointer leads to this error.
Summary message
If your program calls exit(), _exit(), or returns from
main(), a summary message is generated, which shows you the
status returned and a summary of resources used by the pro-
gram.
The first item is a listing of basic memory usage. This
indicates how many bytes of code, data, heap, and stack were
used. All these values include Purify's overhead. The heap
figure represents the finishing size of the heap area, as
indicated by calling sbrk(0). Usually, this indicates the
peak size that the heap reached during execution, unless
your program explicitly relinquishes memory back to the OS
by calling sbrk() or brk() specifying a smaller size.
The second item is a summary of shared library usage, and
memory mapped segment usage if any. Again, the sizes are in
bytes, and include Purify's overhead.
OPTIONS
Purify's operation can be customized for your program. By
specifying options either at program build-time or program
run-time, you can affect which errors Purify reports, what
information the reports contain, how they look, and where
they are displayed or saved. Other options permit you to
control how the program is Purify'd and linked.
Each option is a word or phrase that begins with a hyphen,
for example -leaks-at-exit. Purify ignores the case and any
hyphens or underscores in the option name. The option
-leaks-at-exit is equivalent to -LEAKS_AT_EXIT and
-LeaksAtExit. All options have default values. You may
override these values using the assignment syntax:
-option-name[=[value]]
Note that no spaces are permitted on either side of the
equals sign (=) if it is supplied.
You may specify Purify options:
o on the build-time link line;
o in the environment variables $PURIFYOPTIONS or
$PUREOPTIONS; or
o using the Purify Viewer "Runtime options" dialog in the
"Options" menu.
Link Line Options
Options may be specified on the link line, e.g.:
purify -cache-dir=$(HOME)/pcache $(CC) ...
Build-time options apply to the Purify build command being
run. Run-time options may also be specified on the link
line. These are built into the executable and become the
default values at run-time when the Purify'd executable is
run. This is a convenient way to build a program with non-
standard default values for certain options, for example:
purify -chain-length=12 $(CC) ...
Environment Variable Options
Any option may be specified in the environment variables
$PURIFYOPTIONS or $PUREOPTIONS.
Note: Values in $PURIFYOPTIONS have precedence over values
from $PUREOPTIONS.
Build-time options specified in environment variables are
applied when applications are built. Options specified
explicitly on the build-time link line override environmen-
tal values.
Run-time options specified in environment variables are
applied when Purify'd applications are run. The environmen-
tal values in force when the program is run override any
defaults specified on the link line when the application was
built.
Note: If an option is specified more than once in an
environment variable, the first value is used. To add an
overriding value for the -log-file option, for example,
without changing other options specified, use a command
like:
csh% setenv PURIFYOPTIONS "-log-file=new $PURIFYOPTIONS"
ksh$ export PURIFYOPTIONS="-log-file=new $PURIFYOPTIONS"
Using the Purify Viewer Runtime Dialog
When a Purify'd program runs with the Viewer, the Runtime
dialog may be invoked using the Runtime item from the
Options menu. The options window displays the option values
currently in use while the program is running.
The option values may be edited and applied when the program
has terminated, and the modified values will take effect on
subsequent runs of the program displayed in the Viewer.
These changes are transient, and do not modify either the
default values in the program, or the environment. When you
quit the Viewer and re-run the application, the options will
revert to their original values.
Note: The option values from the Viewer Options window have
to be sent to the application at start-up time, and so it is
not possible to make modifications while the application is
running. However, you can use the Run button to restart the
program with the new option values in effect.
OPTION TYPE DEFAULT
Caching Options (build-time options)
-cache-dir directory purifyhome/cache
This option sets the global directory where Purify'd ver-
sions of libraries will be cached.
-always-use-cache-dir boolean no
This option forces all Purify'd versions of libraries to be
written to the global cache directory. When you use the
default value, Purify caches to the original library's
directory, if it is writable. If the directory is not writ-
able, Purify caches it to the value of -cache-dir.
Linker Options (build-time options)
-linker program-name /bin/ld
This option specifies the name of the linker that Purify
should invoke to produce the executable. You should use
this option only if you need to bypass the default linker.
Output Options (run-time options)
-windows boolean not set
This option is used to control the generation of the Viewer.
If this option is not specified, the Viewer is the preferred
form of output unless one or more of -log-file, -view-file
or -mail-to-user are set.
If this option is set to no, the Viewer will not be gen-
erated, and the preferred form of output will be ASCII to
stderr, unless one or more of -log-file, -view-file or
-mail-to-user are set.
If this option is set to yes, a graphical display window
will be created, in addition to any other output formats
specifically requested, if any.
-log-file file-name not set
If this option is not specified, a graphical display window
will be the preferred form of output unless one or more of
-windows=no, -view-file, or -mail-to-user are set.
If this option is set to -log-file=stderr, ASCII output will
be sent to the program's stderr, in addition to any other
output formats specifically requested, if any.
If this option is set to a filename, ASCII output will be
sent to the named file, in addition to any other output for-
mats specifically requested, if any.
-append-logfile boolean no
This option enables Purify output to be appended to the
current logfile rather than replacing it.
-view-file file-name not set
If this option is not specified, the Viewer will be the pre-
ferred form of output unless one or more of -windows=no,
-log-file or -mail-to-user are set.
If this option is set to a filename, compact binary data
will be written to the named file, in addition to any other
output formats specifically requested, if any. The contents
of this file can then later be viewed with the command:
example% purify -view filename
-output-limit integer 1000000
This option is used in conjunction with the option -log-file
to restrict the size of the logfile and conserve disk space.
The value of this option specifies the maximum size of the
Purify report in bytes. All Purify output is truncated once
this limit is reached.
-copy-fd-output-to-logfile fd list not set
This option enables output from other sources (file descrip-
tors) to be appended to the logfile. This option is speci-
fied as a comma-separated list of file descriptors. Output
written to these file descriptors is copied into the log-
file.
For example, to copy output written to stdout and stderr
into the logfile, interspersed with Purify output, use:
-copy-fd-output-to-logfile=1,2
-follow-child-processes boolean no
This option controls whether Purify monitors child processes
created when a Purify'd programs forks.
If this option is not specified, Purify does not follow
child processes.
If this option is set to yes, Purify invokes a new Viewer
(if appropriate) and monitors the progress of the child pro-
cess separately from the parent, reporting access errors and
memory leaks.
Message Presentation Options (run-time options)
-messages string first
This option controls how repeated messages are handled and
displayed.
If set to -messages=first, only the first occurrence of each
repeated message is displayed. If the same message is gen-
erated again and the output is being sent to the Purify
Viewer, the message is not displayed but the repeat count on
the first message is updated; if the output is being sent to
the tty or a logfile, subsequent repeated messages will not
be reported, though the cumulative total number of messages
in the summary message will still reflect them.
If set to -messages=batch, all error messages are batched
and displayed, along with repeat counts, when the program
exits. This mode is useful when output is not interactively
displayed, but is sent to a logfile or mail mode report and
you wish to note the number of occurrences of each message.
If set to -messages=all, each error message is individually
displayed, in the order generated. This is useful for some
types of interactive debugging, where you need to correlate
repeated occurrences of errors with other program actions.
Note: The Purify version 2 option -first-only is equivalent
to -messages=first, and the Purify version 2 option -batch
is equivalent to -messages=batch. To obtain output similar
to the Purify version 2 default presentation specify
-messages=all.
-mail-to-user user list none
This option specifies a comma-separated list of e-mail
addresses to which the Purify reports are mailed if the pro-
gram reports errors. For example, to send the reports to
Chris and Pat upon completion of the Purify'd application,
use:
-mail-to-user=chris,pat
When mail mode is turned on, by default no output is sent to
the Viewer or to stderr unless you specify the option
-windows=yes or -log-file=stderr.
Message Options (run-time options)
-chain-length integer 6
This option specifies the number of stack frames to be
recorded and printed in the function call chain of a Purify
message. This option also affects the extent of the red
zone area around memory blocks used by Purify to detect
array bound errors. Since Purify stores the call chain of
the function allocating the memory in the red zone at the
end of the block, set this to a larger value to increase
this red zone and increase the extent of the area where
incorrect array boundary accesses will be detected. This
will also change the memory and swap space used by the pro-
gram.
-g++ boolean no
This option tells Purify that the g++ compiler was used and
invokes special processing to avoid spurious ABR errors with
the delete operator. It also sets the default demangling
mode so that g++ mangled function names are properly
resolved. This option is normally set automatically for you
if the compiler is called g++.
-auto-mount-prefix directory /tmp_mnt
This option is used to specify the directory prefix used by
the file system auto-mounter, usually /tmp_mnt, to mount
remote file systems in NFS environments. Use this option to
strip the prefix, if present, to improve the readability of
source filenames in Purify reports.
Note: If your automounter alters the prefix, instead of
adding a prefix, use:
-automount-prefix=/tmp_mnt/home:/homes
to specify that the real file name is constructed from the
apparent one by replacing /tmp_mnt/home with /homes.
If this option is not set correctly, Purify may be unable to
access files on auto-mounted filesystems.
-program-name program name argv[0]
This option specifies the full pathname of the Purify'd pro-
gram if argv[0] contains an undesirable or incorrect value.
This can happen if you change argv[0] in your program, or if
your program is invoked by an exec() call whose path differs
from the argument it passes as argv[0] to your program. In
such cases, Purify can not find the program file, and there-
fore can not interpret addresses as function names.
You may need to use this option if you find little or no
symbolic information in the messages from your Purify'd pro-
gram.
-user-path dir list none
This option specifies a colon-separated list of directories
in which to search to find programs and source code. For
example, if you have a source tree in your home directory
but you also link with GNU source code, you could use:
-user-path=/home/chris/src:/usr/local/gnu/src
Purify searches for the executable file from which to read
the symbol table in your $PATH, and then in directories
listed in -user-path. See also -program-name.
When searching for source-code to show in the Viewer, and
for editing, Purify looks for the file in the full pathname
specified in the compiled-in debug data, then in directories
listed in -user-path, and finally in the current directory.
-show-directory boolean no
This option shows the directory path for each file in the
call chain if that information is present. This information
may not be available if the file is not compiled with the
compiler debug option (usually -g).
-show-pc boolean no
This option shows the full pc value in each frame of the
call chain, facilitating debugging.
-show-pc-offset boolean no
This option appends to each function name in the call chain
the offset of the pc from the start of the function, facili-
tating debugging.
-report-pmrs boolean no
If this option is set, a read of memory which is partially
initialized and partially uninitialized will be reported as
a PMR instead of the usual UMR. The reason to distinguish
these cases is so you can suppress or kill PMR messages,
which happen unavoidably when you have a struct with pad
bytes and you pass it by value as a function argument.
-freeze-on-error boolean no
If this option is set, when an error is reported to the
Purify Viewer, it will delay sending the response back to
the application, which will usually cause the application to
freeze. This is useful to explore the relationship between
error reports and program activity. While the application
is frozen, two new buttons appear at the bottom of the mes-
sage region. Press "Continue" to continue to the next
error, and "Reset freeze-on-error then continue" to continue
uninterrupted.
Note: Do not attempt to use this feature when running with a
debugger. Instead set a debugger breakpoint in the function
purify_stop_here():
(dbx) stop in purify_stop_here
(gdb) break purify_stop_here
(xdb) b purify_stop_here
This is because while the application is frozen by the
viewer, so is the debugger, and you cannot examine variables
or obtain stack traces.
-jit-debug string not set
Purify can automatically attach a debugger to your applica-
tion when selected types of Purify messages are reported.
This provides the convenience of using the debugger to
investigate errors in detail even when you run your applica-
tion from outside the debugger.
Select "JIT Debug..." from the Purify Viewer Options menu
to enable and configure this feature. Alternatively, use
the -jit-debug Purify option on the linkline or in the
PURIFYOPTIONS environment variable, e.g. :
setenv PURIFYOPTIONS "-jit-debug=all"
This string option takes a comma-delimited list of keywords.
"ask" enables a prompting dialog before starting the
debugger. The other keywords control the kind of Purify
messages that will start the debugger.
"error" - fatal/corrupting messages
"warn" - warning messages
"watch" - watchpoint messages
"all" - all of the above
"ask" - prompt to start debugger
Additional customization is possible using the
~/.purify.Xdefaults file and the pure_jit_debug script in
the Purify installation directory.
Memory Leak Options (run-time options)
-leaks-at-exit boolean yes
This option specifies whether or not memory leaked or poten-
tially leaked should be reported at program exit. Memory
leaked is memory that has been allocated but has no pointers
to it, and so cannot be freed.
-inuse-at-exit boolean no
This option specifies whether or not memory in use should be
reported at program exit. Memory in use is memory that has
been allocated but not freed and has valid pointers to it.
-fds-inuse-at-exit boolean yes
This option specifies whether or not file descriptors in use
should be reported at program exit. File descriptors in use
are file descriptors that have been opened, duplicated, or
inherited from the parent process.
-free-queue-length integer 100
This option sets the number of entries in the free queue
maintained by Purify. When you free memory, Purify stores
it into a FIFO queue. When the queue length is exceeded,
the block queued earliest is freed and made available for
re-use. This helps Purify detect free memory accesses (FMW,
FMR). If you have plenty of swap space, you can use this
option to increase the number of entries queued to increase
the likelihood of detecting free memory accesses.
-free-queue-threshold integer 10000
This option sets the maximum size of freed blocks to be
appended to the Purify free queue. Blocks larger than this
are immediately freed and not queued. If you have plenty of
swap space, you can use this option to increase the size of
entries queued to increase the likelihood of detecting free
memory accesses.
-pointer-offset integer 0
This option tells Purify the size of the extra memory allo-
cated by a custom malloc wrapper. If you use a malloc
wrapper that allocates extra memory for bookkeeping purposes
over and above the size requested, and returns an adjusted
pointer past the extra memory allocated, Purify may
incorrectly report potential leaks. This option ensures
that Purify does not report false PLKs.
-pointer-mask hex-mask 0xffffffff
This option specifies a mask that will allow Purify to
extract the correct value from custom pointers. If your
application ORs flags into the upper bits of heap pointers,
Purify cannot follow them to the memory blocks they refer
to, and may incorrectly report leaks. For example, if you
use the upper 4 bits of pointers for flags, use:
-pointer-mask=0x0fffffff
-search-mmaps boolean no
This option tells Purify to search for heap pointers in
mmap'd memory. This option is necessary if you store heap
pointers in mmap'd memory. It is automatically set if you
use ObjectStore (OSCC).
Additional Options (run-time options)
-handle-signals signal list none
-ignore-signals signal list system dependent
Purify issues a SIG message whenever the program receives a
signal that would be fatal. If you want Purify to report
any non-fatal signals, specify them with the -handle-signals
option. If you do not want Purify to report on some sig-
nals, specify them with the -ignore-signals option. This
allows you to specify exactly which signals Purify reports.
The option value is a comma-delimited list of signal names.
The default value of -ignore-signals is system dependent.
The defaults are:
o SunOS 4.1.x:
SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGIOT,
SIGABRT,SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,
SIGSYS,SIGPIPE,SIGTERM,SIGXCPU,SIGXFSZ,SIGLOST,
SIGUSR1,SIGUSR2
o Solaris 2.x:
SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGIOT,
SIGABRT,SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,
SIGSYS,SIGPIPE,SIGTERM,SIGUSR1,SIGUSR2,SIGPOLL,
SIGXCPU,SIGXFSZ,SIGFREEZE,SIGTHAW,SIGRTMIN,
SIGRTMAX
o HP-UX:
SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGABRT,
SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,SIGSYS,
SIGPIPE,SIGTERM,SIGUSR1,SIGUSR2,SIGLOST,
SIGRESERVE,SIGDIL,SIGXCPU,SIGXFSZ
o IRIX:
SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGABRT,
SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,SIGSYS,
SIGPIPE,SIGTERM,SIGUSR1,SIGUSR2,SIGPWR,SIGPOLL,
SIGXCPU,SIGXFSZ,SIG32
For instance, if you want Purify to report on the non-fatal
signals SIGALRM and SIGVTALRM, use:
-handle-signals=SIGALRM,SIGVTALRM
If you do not want Purify to report on the fatal signal
SIGSEGV because your program handles it, use:
-ignore-signals=SIGSEGV
Note: Purify does not handle SIGSTOP, SIGKILL, and SIGTRAP
signals, since doing so interferes with debuggers and
Purify's own operation.
See the man pages for signal() and sigmask(), and the files
/usr/include/signal.h and /usr/include/sys/signal.h for more
information on signals.
-watchpoints-file file-name ./%v.watchpoints
This option specifies the filename where watchpoint settings
should be maintained. The default value is
./%v.watchpoints; the %v will be expanded to the name of
your Purify'd program, thus allowing you to save watchpoints
for multiple programs in the same directory. To disable
saving watchpoints in a file, set this option to an empty
filename, using:
-watchpoints-file=
-exit-status boolean no
This option enables you to control the exit status of your
Purify'd program, based on the types of unsuppressed mes-
sages reported. Purify ORs special bits into the exit
status of the program having the following meanings:
0x40 Memory access errors
0x20 Memory leaks
0x10 Potential memory leaks
Threads Options (run-time options)
-threads boolean no
This option tells Purify that the program uses multiple
threads. If set, Purify will keep track of threads, and
will use appropriate mutex locks to operate in a thread-safe
manner.
This option is set automatically if you link with any of the
supported threads libraries.
-max-threads integer 20
This option specifies the maximum number of threads that
will be used in the program.
-thread-stack-change integer 0x1000
This option specifies the maximum size of a change to the
stack pointer that does not indicate a context change
between threads. Changes larger than this value inform
Purify that the threads package is switching from one thread
to another.
Multi-threaded programs that allocate large objects on the
stack may need to increase this value.
Multi-threaded programs that allocate stack space for dif-
ferent threads close to each other may need to decrease this
value.
-thread-report-at-exit boolean yes
This option specifies whether or not Purify should generate
a report on thread usage at program exit.
The thread report includes information about the number of
threads, and stack space used by each thread.
APPLICATION PROGRAMMING INTERFACE
Purify's application programming interface can be used by
programs as necessary and in interactive debugging environ-
ments like dbx, gdb, and xdb.
Memory Leaks API
int purify_new_leaks()
This function prints an incremental message including all
new leaks. New leaks are leaks introduced since the last
call to the functions purify_new_leaks() or
purify_clear_leaks().
int purify_all_leaks()
This function prints a summary message of all memory leaks.
int purify_clear_leaks()
This function finds leaks and marks them cleared so that the
function purify_new_leaks() will not report them. It does
not print a message. It is useful, for example, for ignor-
ing all leaks from a certain portion of code, perhaps a
start-up sequence.
int purify_new_inuse()
This function prints an incremental message including all
new heap memory allocations. This is memory allocated since
the last call to the functions purify_new_inuse() or
purify_clear_inuse().
int purify_all_inuse()
This function prints a summary message of all heap memory
currently allocated.
int purify_clear_inuse()
This function finds memory in use and notes it as found so
future calls to the function purify_new_inuse() will not
report it. This function does not print a message.
Note that all of the leak detection functions return the
totals of the unsuppressed leaks or memory in-use. This
simplifies usage both programmatically and in the debugger:
(dbx) print purify_new_leaks()
(dbx) print purify_all_inuse()
(dbx) stop in event_loop if (purify_new_leaks())
Logfile API
int purify_logfile_printf(char* fmt, ...)
This function does a formatted print to the logfile, if the
-log-file option is set, or to the mail mode report, if the
-mail-to-user option is set. This function does nothing if
neither option is set.
int purify_printf(char* fmt, ...)
This function does a formatted print to the logfile, if the
-log-file option is set, to the mail mode report, if the
-mail-to-user option is set, or to the standard error stream
if neither is set.
int purify_printf_with_call_chain(char* fmt, ...)
This function does a formatted print to the logfile, if the
-log-file option is set, to the mail mode report, if the
-mail-to-user option is set, or to the standard error stream
if neither is set. It also prints the call chain leading up
to this function call. For example:
if (detect_error) {
purify_printf_with_call_chain (
"Found bad input value %d/n", in_val);
}
This will display the specified string and the function call
sequence to this point. This might help track errant func-
tion call requests without stepping through the debugger.
In this manner, the function purify_printf_with_call_chain()
extends the power of debugging using printf().
Pool Allocation API
void purify_set_pool_id(char* mem, int id)
This function sets the pool-id of memory mem to id.
void purify_set_user_data(char* mem, void* data)
This function sets the auxiliary user data associated with
the pool of memory mem to data.
int purify_get_pool_id(char* mem)
This function returns the pool-id associated with the pool
of memory mem.
void* purify_get_user_data(char* mem)
This function returns the auxiliary user data associated
with the pool of memory mem.
void purify_map_pool(int id, void (*fn) (char*, unsigned))
This function applies the function fn to all members of the
pool of memory identified by pool-id id.
void purify_map_pool_id(void (*fn) (char*, unsigned))
This function applies the function fn to each pool-id known
to the system.
Watchpoints API
int purify_watch(char* addr)
int purify_watch_num(char* addr)
int purify_watch_w_num(char* addr) num=1,2,4,8
These functions allow you to specify watchpoints that detect
writes, allocations, frees, and entry and exit of memory
addresses. The purify_watch_num() and purify_watch_w_num()
functions are identical. You can specify watchpoints for 1,
2, 4 or 8 byte variables using these functions; for example,
to set a write-type watchpoint for eight bytes, use:
(dbx) print purify_watch_w_8(my_double_ptr)
purify_watch() watches 4 bytes. These functions return the
number assigned to the watchpoint.
int purify_watch_r_num(char* addr) num=1,2,4,8
These functions allow you to specify watchpoints that detect
reads, mallocs, frees, and entry and exit of memory
addresses. You can specify watchpoints for 1, 2, 4, and 8
byte variables using these functions; for example, to set a
read-type watchpoint for one byte, use:
(dbx) print purify_watch_r_1(&read_only_char)
These functions return the number assigned to the watch-
point.
int purify_watch_rw_num(char* addr) num=1,2,4,8
These functions allow you to specify watchpoints that detect
reads, writes, mallocs, and entry and exit of memory
addresses. You can specify watchpoints for 1, 2, 4, and 8
byte variables using these functions; for example, to set a
read-and-write-type watchpoint for two bytes, use:
(dbx) print purify_watch_rw_2(&rw_short)
These functions return the number assigned to the watch-
point.
int purify_watch_n(char* addr, unsigned int size, char* type)
This function allows you to set a watchpoint on an arbitrary
sized buffer. addr specifies the address of the beginning
of the buffer, size specifies the number of bytes to watch,
and type specifies whether you want to watch for writes,
with "w"; reads, with "r"; or both, with "rw". For example:
(dbx) print purify_watch_n(write_only_buf, 100, "w")
(dbx) print purify_watch_n(&long_long, 16, "r")
(dbx) print purify_watch_n(buf, sizeof(buf), "rw")
This function returns the number assigned to the watchpoint.
Note: invoking purify_watch_n() in a debugger, you can use
integer values 1, 2, and 3 for "r", "w", and "rw" respec-
tively if your debugger makes it hard to call functions with
string arguments.
int purify_watch_info()
This function lists the active watchpoints. This function
returns 0.
int purify_watch_remove(int watchno)
int purify_watch_remove_all()
The function purify_watch_remove() removes the watchpoint
specified by watchno. The function
purify_watch_remove_all() removes all watchpoints. Both of
these functions return 0.
Additional Functions
int purify_describe(char* addr)
This function prints specific details about the memory
pointed to by addr, including its location (stack, heap,
text, etc.) and, for heap memory, the call chains of its
malloc and free history.
int purify_what_colors(char* addr, unsigned int size)
This function prints out the memory state of size bytes
starting at memory address addr. The letters RYGB each show
the color of one byte of memory, and represent Red, Yellow,
Green, and Blue.
o Red: The heap memory is initially red. Red means that
the memory is unallocated and uninitialized. It has
either never been allocated or it has been allocated
and subsequently freed. It is illegal to read, write
or free red memory because it is not owned by the pro-
gram.
o Yellow: Memory returned by malloc is yellow. Yellow
means that the memory has been allocated, but is unini-
tialized. The program now owns this memory. It is
legal to write yellow memory, or free it if it was
allocated by malloc, but it is illegal to read it
because it is uninitialized. Stack frames are set to
yellow upon function entry.
o Green: Once yellow memory has been written, it becomes
green. Green means that the memory is allocated and
initialized. It is legal to read or write green
memory, or free it if it was allocated by malloc. The
data and bss sections of memory (initialized and zeroed
global memory and static data) are automatically ini-
tialized to the green state.
o Blue: Memory which has been freed after it was initial-
ized and used is blue. Blue means that the memory has
been initialized, but is no longer valid for access.
It is illegal to read, write or free blue memory.
int purify_is_running()
This function returns 1 if the executable is Purify'd, 0
otherwise. This function may be used to enclose special
purpose application code to execute in the Purify'd environ-
ment. For example:
if (purify_is_running()) {
install_gui_leaks_button();
}
int purify_assert_is_readable(const char* addr, int size)
int purify_assert_is_writable(const char* addr, int size)
These functions are used to assert the readability or writa-
bility of the address specified by addr for size bytes. The
function purify_assert_is_readable() returns 1 if the memory
is allocated and initialized (green), otherwise 0, whereas
purify_assert_is_writable() returns 1 if the memory is allo-
cated (yellow or green), otherwise 0.
void purify_exit(int status)
This function calls the exit system call, but arranges to
have the exit status augmented to show whether Purify
detected access errors (0x40), memory leaks (0x20), or
potential memory leaks (0x10). The appropriate bits are
ORed into the status passed to purify_exit().
FILES
*_pure_*
Cached object and library files translated by Purify.
purifyhome/cache/...
Central cache directory structure for caching
translated object files and libraries when they cannot
be written alongside the original files.
.pure, .lock.*
Locking files preventing simultaneous file access by
more than one user.
.purify, .purify.sunos4, .purify.solaris2, .purify.hpux
Used to specify suppression directives for Purify.
*.watchpoints
Watchpoint settings saved from one run to the next.
purifyhome/../purela/*
Contains passwords and a list of regular users for use
by the Pure License Advisor.
purifyhome/purify.h
Include file to use with Purify API.
purifyhome/purify_stubs.a
Library to be included to provide dummy Purify API
function definitions for use when not linking under
Purify.
purifyhome/Purify.XResources
Default X resource values.
SEE ALSO
purecov(1), repurify(1), dbx(1), gdb(1)
CAVEATS
Occasionally, wild random pointers accidentally point into a
valid heap block. Purify checks pointer validity, and not
pointer arithmetic, and thus cannot signal an error in such
cases. Purify's watchpoints can help you track down such
wild pointer errors.
A Purify'd program normally runs about 3 to 5 times slower,
and takes about 40% more memory, than if not processed by
Purify. Occasionally the additional memory required will
cause the paging behavior to degrade performance to a
greater degree. In this case, running the Purify'd program
on a machine with more memory would be advantageous.
Programs instrumented on one version of Solaris may crash or
generate incorrect results if run on a different version of
the operating system.
A Purify'd program can, because of its different memory
usage patterns, cause code that works by accident to behave
slightly differently. For example, values read from unini-
tialized or unallocated locations can differ with and
without Purify. You will get Purify error messages for all
such code. Purify will not change the behavior of your code
in any other way.
If Purify does change the behavior of the program (except as
mentioned above), or produces incorrect error reports,
please report such bugs to the appropriate address:
Contact us in the US at:
support@rational.com or (408) 863 4000
In Europe:
support@europe.rational.com or +31 (0)20 4546 200
In Japan:
support@japan.rational.com or +61 (2) 9419 0111
Man(1) output converted with
man2html