14    Heap Analyzer

This chapter provides an overview of the Heap Analyzer's features and capabilities. For more detailed information on how to use this tool, choose Help: On Heap Analyzer. You can print Help topics using the HyperHelp Viewer.

The FUSE Heap Analyzer finds and displays memory errors and memory leaks in a program. You can view the data in graph or text format.

The Heap Analyzer uses the Third Degree utility to find memory errors.

Figure Figure 14-1 shows the Heap Analyzer main window.

Figure 14-1:  Heap Analyzer Main Window

Key elements are the major window panes running from the top to the bottom of the window:

Configuration area

Displays the current project, working directory, target executable file, and directory in which the memory data is stored.

Setup area

Lets you specify the criteria to use when generating data.

Display area

Shows either your program's input and output or data generated by the Heap Analyzer.

Information area

Displays information messages and Quick Help on menu items when you press and hold MB1 on the item.

14.1    Summary of Features

The Heap Analyzer does the following:

• Provides a graphic, integrated interface to the Third Degree utility

• Executes your program to find memory errors and memory leaks

• Displays and reviews memory errors and leaks in histogram format

• Displays the source associated with memory errors and leaks through integration with editors

• Collects memory errors and leaks for multithreaded applications

14.2    Requirements for Using the Heap Analyzer

To use the Heap Analyzer, make sure that:

• A working executable file of the target program is available as specified in the Project Manager. The Heap Analyzer runs the executable file to generate memory data. If the executable file has run-time errors, limited memory data will be generated.

• The Third Degree utility is available on your system. Third Degree is part of the Digital UNIX operating system: Software Development Tools and Utilities. See your system manager if necessary.

14.3    Compiling Your Program

Before you can get memory data on your program using the Heap Analyzer, you must first compile and link your program. The Third Degree utility does not require you to compile with any specific compiler option. However, you will get better information if your program has some debugging information. We recommend compiling with the -gl switches, which adds file names and line numbers.

14.4    Starting the Heap Analyzer

After you compile and link your program, you are ready to start the Heap Analyzer. You can start the Heap Analyzer in several ways:

• Use the command line.

• If you have CDE installed, use the Heap Analyzer icon.

• Use the FUSE Control Panel once FUSE is running.

• Use the Tools menu from most FUSE tools.

14.4.1    Use the Command Line

To start the Heap Analyzer from the command line, use the following command:

% fuseheap [-cwd] [-data directory-path] [Xt-Options]
[target]

See Appendix Appendix D and the specific reference pages for the command syntax and options.

If the Control Panel is not running, it starts automatically as a minimized icon. If FUSE is already running, the Heap Analyzer is placed in the current project.

14.4.2    Use the Heap Analyzer Icon from CDE

When you have CDE installed, FUSE provides a FUSE application group icon and icons for the individual tools that make up the FUSE environment.

To start the Heap Analyzer:

1. Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.

2. Double click on the FUSE application group icon to display the icons in the FUSE application group.

3. Double click on the Heap Analyzer icon to start the tool.

14.4.3    Use the FUSE Control Panel

To start the Heap Analyzer from the FUSE Control Panel:

1. Select Heap Analyzer from the Tools menu in the Control Panel.

2. If you haven't already specified a target executable, an informational box prompts you to specify one. The target executable is the program for which the Heap Analyzer will generate and display memory data. Click on OK in this box to display the Project Manager for setting project configuration settings.

3. In the Project Manager, enter the target executable in the Executable Target field.

4. Optionally, enter a Data Directory, which the Heap Analyzer will use to store the generated memory data. (This data directory is also used by the Profiler to store profiling data.)

5. Optionally, enter one or more directories in the Source Directory List box. These directories are checked for source files if the Heap Analyzer (and Profiler and Builder) cannot find the files in the working directory or data directory.

6. Click on OK in the Project Manager and the Heap Analyzer main window appears.

14.4.4    Use the Tools Menu from Most FUSE Tools

Most FUSE tools have a Tools menu. To start a tool, select the tool from the Tools menu.

14.5    Heap Analyzer Actions

The Heap Analyzer is always in one of two modes of action:

• Generating data

• Showing data

Use the Action options menu in the Heap Analyzer main window to choose which action you want:

The Heap Analyzer window dynamically changes, as shown in the following sections, depending on which action you select.

14.5.1    Generate Data Action

Figure Figure 14-2 shows the display area when the Generate Data action is selected. Table Table 14-1 lists the additional window components that are displayed for this action.

Figure 14-2:  Heap Analyzer Window with Generate Data Action Selected

Table 14-1:  Window Components for the Generate Data Action

Component	Description
Setup... button	Click on this button to bring up a dialog box to specify the criteria to use when generating data.
Create Unique Data Files Per Run check box	Check this box if you want the process ID to be included in each data file name so that each data file is unique. Every data file created is added to the list of data files instead of replacing an old data file.
Optional Arguments for Target field	When the Heap Analyzer runs your program to generate data, it invokes the program using the information you specify here. Use this field to enter any command-line arguments that the program requires as you would in a terminal window using your shell. You can use environment variables, quoted strings, and I/O redirection as you would in your shell.
Tool Options... button	Click on this button to set options for the Third Degree utility.
Run/Stop Run button	Click on the Run button to run the executable file and generate memory data. When you click on Run, this button automatically changes to Stop Run, allowing you to stop the execution of your program. If you click on Stop Run, the Heap Analyzer may not generate a valid modified application or a valid data file, depending how far the Heap Analyzer had gone in its data collection.
Target's Input/Output:	When you click on the Run button to generate data, this area shows the output from the target program and displays any request for input from the program. You can enter program input directly in this area.

For more information on how to generate data, chooseHelp: On Heap Analyzer or Help: FUSE Tutorials from the Heap Analyzer.

14.5.2    Show Data Action

Figure Figure 14-3 shows the display area when the Show Data action is selected. Table Table 14-2 lists the additional window components that are displayed for this action.

Figure 14-3:  Heap Analyzer Window with Show Data Action Selected

Table 14-2:  Window Components for the Show Data Action

Component	Description
Setup... button	Click on this button to bring up a dialog box to specify the criteria to use when showing data.
Filters... button	Click on this button to bring up a dialog box to specify which items are filtered from the display when showing data.
Show options box	Click on this box to choose the type of data you want to display.
As options box	Click on this box to choose the display format for the data selected in the Show options box. See Table 14-3 for a description of display formats.
Data File(s) field	This field shows the data file or files from which memory data has been generated. You can enter multiple file names in this field, separated by spaces, and can use wildcards. Use the Pick... button to browse for files.
Apply button	Click on this button to display the memory data.
Display area	This area shows the currently selected memory data.

14.5.2.1    Types of Data and Display Formats

The Heap Analyzer generates and displays the following types of data:

• Memory errors of all types

• Memory read errors

• Memory write errors

• Memory allocation errors

• Memory leaks

When you generate memory data, you can view the data using the display formats shown in Table Table 14-3.

Table 14-3:  Heap Analyzer Display Formats

Format	Description
Text	Displays the data as simple text in a chart format.
Simple histogram	Displays the data as a histogram, typically with the function, register, or instruction in the left column and the displayed values in the right column.
2-level histogram	Displays the data as a histogram similar to the simple histogram. If you double click on an entry in the display, the Heap Analyzer displays additional information.
Program Visualizer	Displays the data using the FUSE Program Visualizer.

14.5.2.2    Showing More Detailed Information

When the memory data is displayed, you can click on an error or leak to display a list of functions that were called that led to the error or leak. You can then press MB2 on a function name to invoke the editor and display the source code for that function. The Heap Analyzer places a colored icon in the Editor annotation area next to the referenced line.