Calling Purify API functions

You can call Purify API functions from a debugger or from your program.

Calling Purify API functions from a debugger

You can call many Purify functions interactively from a debugger. Some, such as the watchpoint functions, the leak-detection functions, purify_describe, and purify_what_colors, are especially useful when used with a debugger:

(gdb) print purify_describe(addr)
(dbx) print purify_what_colors(buf, sizeof(buf))
(xdb) p purify_describe(addr)

Note:

• You can force your debugger to stop on every Purify error message, right before the error actually occurs in your program. This allows you to call API functions from your debugger in order to investigate the problem. To do this, set a debugger breakpoint on the function purify_stop_here, as follows:
  
  (gdb) break purify_stop_here
  (dbx) stop in purify_stop_here
  (xdb) b purify_stop_here
  
  For an example of how to use purify_stop_here, click
  
  Setting a breakpoint on the function also stops the debugger at any point in your source code where you have inserted a call to purify_stop_here_internal.

Calling Purify API functions from your program

You can automatically control error data collection and reporting by calling Purify API functions from within your program. For example, you can use purify_is_running to keep Purify function calls from slowing down your program when code that is not instrumented is executing.

To call Purify functions from ANSI C and C++ programs, include the file purify.h:

# include <purify.h>

This header file is located in the same directory as Purify. Add the compiler option -I<purifyhome> or -I`purify -printhomedir` in your makefile, if necessary.

Using the API stubs library

If you call Purify functions in your program, you must link with the Purify API stubs library (unless you use #ifdef to control the execution of these functions). This is a small library that stubs out all the Purify API functions when you are not using Purify. When you are using Purify, Purify provides the real definitions for the API functions, and the stubs are ignored; you do not need to change your link line.

For 32-bit Solaris and HP-UX systems:

Add the library <purifyhome>/lib32/libpurify_stubs.a to your link line.

For 64-bit Solaris and HP-UX systems:

Add the library <purifyhome>/lib64/libpurify_stubs.a to your link line.

For IRIX systems:

Purify on IRIX includes both a shared and an archived version of the stubs library. If you are using the N32 Application Binary Interface (ABI), link with these versions of the stubs library:

<purifyhome>/lib32/libpurify_stubs_n32.so

<purifyhome>/lib32/libpurify_stubs_n32.a

 For the O32 ABI, link with:

<purifyhome>/lib32/libpurify_stubs.so

<purifyhome>/lib32/libpurify_stubs.a

For a 64-bit platform, the libraries are:

<purifyhome>/lib64/libpurify_stubs.so

<purifyhome>/lib64/libpurify_stubs.a

Note:

• Purify includes the source code for purify_stubs.a (pure_stubs.c and purify.h) without copyright. You can include it in the libraries you ship to customers, or compile it on other platforms. This allows you to include calls to Purify API functions throughout development and testing, without having to re-compile or change your code for final shipment.

Installing libpurify_stubs.so on IRIX systems

In the examples below, replace <purifyhome> with the path to your Purify installation.

If ld is available when you install Purify, the full pathname is automatically encoded in libpurify_stubs.so.

If ld is not available, Purify uses the default path /usr/pure/purify.

If you do not install Purify in /usr/pure/purify and ld is not available, libpurify_stubs.so is installed without a built-in path. You can specify the pathname by typing:

% ld -shared -all -soname \
<purifyhome>/libpurify_stubs.so -o \ <purifyhome>/libpurify_stubs.so \ <purifyhome>/libpurify_stubs.so.std

You can also use libpurify_stubs.so without a path, then specify it at run time by typing:

% cc <program>.c `purify -printhomedir`/libpurify_stubs.so
% setenv LD_LIBRARY_PATH `purify -printhomedir`
 % a.out

Linking with libpurify_stubs.so on IRIX systems

During development, link your program with the libpurify_stubs.so library by typing:

cc <program>.c <purifyhome>/libpurify_stubs.so

This resolves any API references in your code and lets you use the API when you Purify the program.

Warning: Do not ship a program linked with the libpurify_stubs.so library. It will cause a fatal error when the library is not found at run time.

Linking with libpurify_stubs.a on IRIX systems

To produce a program for non-Purify users, link with the libpurify_stubs.a library by typing:

cc <program>.c <purifyhome>/libpurify_stubs.a

This disables Purify API functions. If you Purify a program linked with this library, Purify API functions are ignored.