Contents

Legal Notices

Chapter 1:
  Quick Start


Chapter 2:
  Introduction and Installation


Chapter 3:
  About Memory Analysis


Chapter 4:
  Finding Memory Leaks


Chapter 5:
  Finding Memory Errors


Chapter 6:
  Startup Options


Chapter 7:
  Viewing Error Messages


Chapter 8:
  Viewing Source Code


Chapter 9:
  Tips and Techniques


Chapter 10:
  Troubleshooting


Chapter 11:
  Obtaining Support


Chapter 7: Viewing Error Messages

There are two ways to view the error reports that ZeroFault generates. By default, ZeroFault creates a graphical user interface (GUI) to display the errors generated for each session. In addition, the zf_rpt command can be used to generate an ASCII text version of the error report.

The ZeroFault Graphical User Interface

ZeroFault creates a graphical user interface to display the error messages if the DISPLAY environment variable is set or if the -d option is specified. The user interface can be disabled by specifying -d none.

If either of the above conditions are met, ZeroFault creates an instance of the GUI for each invocation of ZeroFault. ZeroFault also creates a new GUI to display the output of any forked child of a process if the -c option is specified on the command line. Finally, ZeroFault creates a new GUI for each program loaded by an exec call if the -e option is specified on the command line.

It is important to understand the flow of the program being debugged, to know whether it calls fork or exec, and to decide whether you want ZeroFault to "follow" the forks and execs and create new GUIs for them. Normally, when a program calls exec its execution is considered terminated, and the new program takes over if the exec succeeds. The -e flag allows you to continue running ZeroFault against any programs that are loaded by the initial debugged program.

You can also run a ZeroFault GUI from the command line to view the contents of any ZeroFault output file. An output file is created for every ZeroFault instance; it contains the full error report and any other information about the debugging session.

To start the ZeroFault GUI from the command line, enter:

	zf_ui <zf_out_file>
where <zf_out_file> is the name of the ZeroFault output file. Various options that affect the appearance and behavior of the user interface can be specified using X-Windows resources.

Error Message Appearance

ZeroFault displays errors in an outline form in the GUI's main error pane (the one with the white background). By default, errors are initially shown in a summary (collapsed) form, with a right-pointing arrow icon at the beginning of each error message. Clicking the left mouse button on a message line makes the GUI expand the message into its detail form, showing the relevant memory location, tracebacks, etc. Clicking again on the line collapses the message back to its summary form. The error tracebacks are also shown in summary form, and can be expanded and collapsed in the same way.

You can alter the appearance of the error message display by selecting different message sorting and grouping criteria. As the program executes and messages are generated, ZeroFault continually updates the display according to these criteria.

Error Message Sorting

The order in which error messages are displayed is determined by the criteria selected in the Sort By menu in the error message pane. There are four different sorting criteria, as follows:

Error Message Grouping

In order to present the errors in a more usable format, ZeroFault can condense similar error messages into a single line of output in the error pane. Groups of condensed messages are signified by a double-arrow icon on the left side of the line. To view individual errors in a condensed group, click the left mouse button anywhere on the condensed group. This "peels off" and expands a message from the group of similar messages. To collapse an expanded message and condense it back into a group of similar messages, click the left button anywhere on its first line.

You can specify the criteria that ZeroFault uses to condense messages using the following options on the Condense By menu:

  • None

    Performs no grouping and shows all errors in the error message display pane.

  • Module

    Groups errors generated by statements within the same program module. Modules consist of the debugged executable itself, any shared libraries that were loaded with it, and any dynamically loaded modules that it explicitly loaded.

  • Source File

    Groups errors generated by statements within the same source file. This is useful for a functional view of the detected errors if the application's source files map to a functional grouping of the application.

  • Function

    Groups errors detected within the same function; this is the default option.

  • Error Location

    Groups errors by the exact instruction where the error occurred.

  • Complete Traceback

    Groups errors by the full traceback of where the error occurred.

Error Message Filtering

ZeroFault allows you to specify certain error messages that you don't want displayed. For example, you may choose to filter out error messages for modules over which you have no control. The unwanted messages are specified using the filter list, which can be manipulated in a number of ways.

The Message Filters menu contains several options that affect error filtering; the menu is shown below with the Disable Filtering and Discard Filtered Messages toggle buttons disabled, which is their default state:

These options, and other means of modifying the filter list, are described in the following sections.

Adding an error to the filter list

Error messages can be hidden from view by adding them to the filter list. If you want to add many errors at once, it may be best to directly edit the filter list. To add an individual error to the filter list, click anywhere on it with the right mouse button to bring up the error message popup menu. The error type and location is listed at the top of the menu, which contains the following options:

  • Add to Filter List
    Adds the error message to the list of errors to suppress. Note that ZeroFault does not prevent you from adding duplicate errors to the filter list.
  • Add and Apply
    Adds the error message to the list and immediately applies the new filter rule, causing the message to disappear from the error pane. The accelerator for this menu option is Ctrl-Left Mouse Button.
  • Show Source
    Displays the source related to the selected error. The accelerator for this menu option is Shift-Left Mouse Button.

Editing the filter list

Selecting the Edit Filter List option from the Message Filters menu brings up a window that allows you to directly edit the filter file. The syntax for the filter file entries is:

	# <comment>
	<error type> <location>

Error type can be any of the error type abbreviations (UMR, BMW, etc.). The error type can also be "ANY", which matches any error.

Location specifies the location at which an error must occur in order to be suppressed. Location can be specified in any of the following forms:

  • file <source file name>[:<line number>]
  • function <function name> [+0x<hex offset>]
  • function '<function name regular expression>'
  • module <executable module name>[(archive member name)]
  • anywhere
  • The fields in []'s are optional.

Errors are suppressed that match any filter list entry's error type and location.

If the location is a function then the function name may be specified as an extended regular expression enclosed in single quotes ('). Refer to the AIX reference for the egrep command for further information on extended regular expressions.

An example filter file is:

	ANY module libXt.a
	BMR function foo +0x10
	WNULL anywhere
	UMR file myfile1.c:20
	UMR function '^str.*|^mem.*'
	USTKR file myfile2.c

This file causes ZeroFault to suppress the following errors:

  • Any errors that occur in the libXt.a module.
  • BMR errors that occur at the instruction at offset 0x10 in function foo.
  • WNULL errors that occur anywhere.
  • UMR errors that occur at line 20 in file myfile1.c.
  • UMR errors that occur in any function whose name begins with str or mem.
  • USTKR errors that occur anywhere in file myfile2.c.

If you directly select errors for the filter list while the filter list edit window is open, ZeroFault will update the window with your selections.

A filter list may be saved, applied to the current error messages, or loaded from a previously-saved filter list file. For example, to start a ZeroFault session on a target application with a filter list which was created from a previous session:

  1. Start ZeroFault with the target application.
  2. Select the Edit Filter List menu item.
  3. Press the Load button.
  4. Select the appropriate file from the file selection dialog.
  5. Press the Apply button.

If ZeroFault detects an error in the filter list, it will display a warning dialog box.

Temporarily turning off filtering

You can toggle filtering on or off by selecting the Disable Filtering toggle button in the Message Filters pulldown menu.

Discarding Messages

Even when messages are filtered, they still are retained by the GUI by default, and may be viewed by removing them from the filter list. You may choose instead to discard filtered messages.

Discard messages as they are filtered by selecting the Message Filters pulldown menu and turning on the Discard Filtered Messages toggle button. Discard all currently displayed messages (including any which were filtered and not displayed) by selecting the Discard Current Messages menu item from the Message Filters pulldown menu.

Saving Messages

You can save error messages to an ASCII format output file in two ways: fully expanded and currently displayed. To create an output file that contains the fully expanded error messages, select the Save Expanded option from the File pulldown menu. If you select the Save option then the file will contain the messages as they currently appear on the screen.

Generating Text Reports

The zf_rpt command converts a ZeroFault output file to an ASCII version suitable for text manipulation or editing.

The syntax is:

	zf_rpt [<options>] <filename>

The flag options are:

-t

Creates single-line terse output suitable for manipulating with text utilities such as sort and grep. The width of the output lines and the spacing between columns are controlled by the -w and -c flag options, respectively.

-w <width>

Controls the total line width of the output for -t style output. The output will have no more than <width> columns of information per line. This will often cause the stack tracebacks to be truncated.

-c <chars>

Controls the number of characters per column and is most useful to adjust the spacing between columns of output in terse mode with extremely long or short function names.

The output of zf_rpt is sent to the standard output stream. Note that error messages are not sorted or condensed when viewed using zf_rpt; all error messages are reported, and they appear in the order in which they occurred.

A useful way of quickly assessing the state of an application is to run ZeroFault against it and then use zf_rpt to summarize the error messages:

	$ zf_rpt -t <output file> | sort | uniq -c | more
The output contains unique errors, one per line, with a count of the number of duplicates preceding each message.

© Copyright 2013 The ZeroFault Group, LLC. All rights reserved. All logos and trademarks are property of their respective owners.